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Preface 


The VMS Device Support Manual provides information needed to write a 
device driver that runs under VMS Version 5.0 and to load it into the 
operating system. DIGITAL makes no guarantee that drivers written for 
earlier versions of VMS will execute without modification on this version 
of the operating system. Although the intent is to maintain the existing 
interface, some unavoidable changes might occur as new features are added. 





Intended Audience 


This manual is intended for system programmers who are already familiar 
with VAX processors and the VMS operating system. 





Document Structure 


This manual contains the following four parts: Part I describes the 
components and environment of a device driver and provides explanations of 
VMS concepts critical to an understanding of a device driver’s functions and 
role in the operating system. Part I contains the following sections: 


e Chapter 1 describes the role of a device driver in the VMS operating 
system, introduces the components of a typical driver and the data 
structures it uses, and provides an overview of system concepts critical to 
driver operation. It concludes with an examination of the I/O subsystems 
of the VAX processing systems. 


e Chapter 2 provides an example of a device driver—the VMS line printer 
driver, and illustrates the functions of the various components of this 
driver and describes the driver’s interaction with VMS. 


¢ Chapter 3 discusses VMS synchronization mechanisms: interrupt priority 
levels; spin locks, fork locks, and device locks; fork processes and fork 
queues; and resource-wait queues. 


¢ Chapter 4 provides an overview of I/O processing and discusses the 
interaction of device drivers with VMS. 


Part II of this document describes how to code each part of a driver, and 
includes the following sections: 


e Chapter 5 explains some general driver coding rules and conventions, and 
includes a template of a device driver. 


e¢ Chapter 6 describes how to create driver tables, including the driver 
prologue table, driver dispatch table, and function decision table (FDT). 


e Chapter 7 explains how to write FDT routines, use VMS-supplied FDT 
routines, and transfer control out of I/O request preprocessing. 


e Chapter 8 discusses the components of a driver’s start-I/O routine. 


e Chapter 9 discusses the functions performed by an interrupt service 
routine. 


e Chapter 10 describes how to perform device-dependent I/O completion 
and write timeout handling routines. 
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Chapter 11 describes unit and controller initialization routines, cancel-I/O 
routines, error logging routines, register dumping routines, and cloned 
UCB routines. 


Part III contains discussions of bus-specific and processor-specific details 
that affect the composition and operation of a device driver. It also contains 
chapters that discuss advanced topics relating to the writing of specific types 
of drivers. 


Chapter 12 discusses I/O bus features that govern the operation of 
direct-memory-access (DMA) transfers and affect the code of DMA device 
drivers for UNIBUS and MicroVAX Q22 bus devices. 


Chapter 13 describes strategies for producing a MASSBUS device driver. 


Chapter 14 describes special coding considerations for generic VAXBI 
devices. 


Chapter 15 examines the methods by which a device is logically 
connected to the processor and by which a driver is loaded into the 
operating system. 


Chapter 16 describes the use of XDELTA as a device driver debugging 
tool. 


Chapter 17 discusses the components of terminal class and port drivers. 


Chapter 18 describes the connect-to-interrupt driver interface that is 
available to real-time users. 


Part IV is a reference section, and includes the following appendixes: 


Appendix A contains a set of figures and tables that describe the contents 
of each data structure and table in the I/O database. 


Appendix B lists the VMS macros usually invoked by drivers. 


Appendix C describes the context, synchronization, and I/O requirements 
of the executive routines used by drivers or called as the result of a driver 
macro invocation. 


Appendix D supplies a condensed description of the function and 
environment of each driver routine. 


Appendix E includes a sample driver that operates an RLO1/RL02-type 
disk on the UNIBUS or Q22 bus. 


Appendix F contains a sample driver for two connected DR11 controllers 
on the UNIBUS or Q22 bus. 


Appendix G describes the differences between drivers intended for a VMS 
uniprocessing environment and those intended for a VMS multiprocessing 
environment. It further describes those changes that DIGITAL requires 
or recommends in all existing non-DIGITAL-supplied drivers because of 
the release of VMS Version 5.0 and also discusses the means by which a 
uniprocessing driver can be converted to a multiprocessing driver. 


The glossary at the end of this manual defines the vocabulary that pertains to 
device drivers and their environment. 


Preface 





Associated Documents 


Before reading the VMS Device Support Manual volume, you should have an 
understanding of the material discussed in the following documents: 


VAX Hardware Handbook 
I/O-related portions of the VMS System Services Reference Manual 


The section on VMS naming conventions in the Guide to Creating VMS 
Modular Procedures 


VMS I/O User's Reference Manual: Part I and VMS I/O User’s Reference 
Manual: Part I 


You may also find useful some of the material in your processor’s hardware 
documentation, as well as in the following books: 


VMS System Dump Analyzer Utility Manual 
Guide to Maintaining a VMS System 
VAX/VMS Internals and Data Structures 
VMS Delta/XDelta Utility Manual 





Conventions 


This manual describes code transfer operations in three ways: 


1 


2 
3 


The phrase “issues a system service call” implies the use of a CALL 
instruction. 


The phrase “calls a routine” implies the use of a JSB or BSB instruction. 


The phrase “transfers control to” implies the use of a BRB, BRW, or JMP 
instruction. 


Typographical conventions used in this book include the following: 


Generally, terms that are further explained in the glossary of this manual 
first appear in italic print. For example: 


Under the VMS operating system, a device driver is a set of routines and 
tables that the system uses to process an I/O request for a particular 
device type. 


Terms that serve as arguments to macros appear in boldface in the text of 
the manual. For example: 


If an at-sign character (@) precedes the oper argument, then the exp 
argument describes the address of the data with which to initialize the 
field. 


In examples, a symbol with a one- to six-character abbreviation indicates 
that you press a key on the terminal. For instance: 


driver-base-address ,0;X 


XXXi 


Preface 


XXXii 


In examples, the symbol <CTRL/x> indicates that you must press 
the key labeled CTRL while you simultaneously press another key. For 
instance: 


$ CREATE MYDRIVER. OPT 
BASE=0 
[crrL/z] 


A horizontal ellipsis indicates that additional parameters, values, or 
information can be entered. For example: 


$LINK /NOTRACE MYDRIVER1[,MYDRIVER2,...],- 
MYDRIVER.OPT/OPTIONS, - 
SYS$SYSTEM: SYS .STB/SELECTIVE_SEARCH 


Square brackets indicate that the enclosed item is optional. (Square 
brackets are not, however, optional in the syntax of a directory name 
in a file specification or in the syntax of a substring specification in an 
assignment statement.) 


DSBINT [ipl] [,dst] 


Command examples show in black letters all output lines or prompting 
characters that the system prints or displays. All user-entered commands 
are shown in red letters. For example: 


>>>DEPOSIT R3 0 
>>>@DMAXDT 
SYSBOOT> 
SYSBOOT>CONTINUE 


A vertical ellipsis means either that not all the data that the system would 
display in response to the particular command is shown or that not all 
the data a user would enter is shown. For example: 


JSB @UCB$L_FPC(R5) ; Restore the driver process. 


;Between these instructions, the interrupt service routine 
;can make no assumptions about the contents of RO through R4. 


POPR #°M<RO,R1,R2,R3,R4,R5> ; Restore interrupt registers. 


New and Changed Features 


The VMS Device Support Manual reflects various enhancements and changes 
to VMS evident in VMS Version 5.0. It also incorporates information useful 
in the creation of device drivers for those VAX processors introduced since 
VMS Version 4.4, including the VAX 8250, VAX 8300, VAX 8530, VAX 8550, 
VAX 8670, VAX 8800, VAX 8830, VAX 8840, the VAX 6200 series, and the 
MicroVAX 3600 series. 


Among the new features discussed in this manual are the following: 


VMS Version 5.0 incorporates support for symmetric multiprocessing 
(SMP) in VAX multiprocessing systems, such as the VAX 8300/8350, VAX 
8800/8830/8840, and the VAX 6200 series. Drivers designed to run in a 
multiprocessing environment must supplement IPL synchronization with 
the additional synchronization mechanism of spin locks. 


For a full discussion of the impact of VMS Version 5.0 on existing 
non-DIGITAL-supplied drivers, refer to Appendix G. Appendix G also 
discusses the means by which you can convert a driver designed to 
execute in a VMS uniprocessing system so that it also runs in a VMS 
multiprocessing system. 


Chapter 3 supplies a full discussion of the rules for synchronizing drivers. 


Appendix B includes descriptions of the following new synchronization 


macros: 
DEVICELOCK Achieves synchronized access to a device's database as 
appropriate to the processing environment 


DEVICEUNLOCK Relinquishes synchronized access to a device's database 
as appropriate to the processing environment 


FORKLOCK Achieves synchronized access to a driver's fork 
database as appropriate to the processing environment 


FORKUNLOCK Relinquishes synchronized access to a driver’s fork 
database as appropriate to the processing environment 


LOCK Achieves synchronized access to a system resource as 
appropriate to the processing environment 


UNLOCK Relinquishes synchronized access to a system resource 
as appropriate to the processing environment 


Additionally, Appendix B explains new requirements governing the use of 
the following existing macros: 


DSBINT Blocks interrupts from occurring on the local processor 
at or below a specified IPL 

ENBINT Lowers the local processor's IPL to a specified value 
and thus permits interrupts to occur at or beneath the 
current IPL 

SETIPL Sets the current IPL of the local processor 


XXXili 
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Appendix B also describes the following new macros that synchronize 
certain tasks of privileged code in both a multiprocessing and 
uniprocessing environment: 


FIND_CPU_DATA Obtains the starting virtual address of the current 
processor's per-CPU database structure 
READ_SYSTIME Obtains a consistent copy of the system time and 


places it into the specified quadword destination 


INVALIDATE_TB Flushes a single page-table entry or all page-table 
. entries from the system’s translation buffers 


Appendix C includes descriptions of all routines, invoked by the macros 
listed above, that obtain and release spin locks, fork locks, and device 
locks. It includes the following routines: 


SMP$ACOQNOIPL Acquires a device lock, assuming that the 
local processor is already running at the IPL 
appropriate for the acquisition of the lock 


SMP$ ACQUIRE Acquires a fork lock or a spin lock and enforces 
the appropriate IPL synchronization on the local 
processor 


SMP$ACQUIREL Acquires a device lock and enforces the 
appropriate IPL synchronization on the local 
processor 


SMP$RELEASE Releases any and all acquisitions of a fork lock or 
a spin lock by the local processor and makes the 
lock available for acquisition by other processors 


SMP$RELEASEL Releases any and all acquisitions of a device 
lock by the local processor and makes the lock 
available for acquisition by other processors 


Section 15.3 discusses the issues involved in loading a multiprocessing 
driver into the system, and Section 16.14 describes the VMS 
synchronization images and their role in testing a multiprocessing driver. 


Finally, Appendix A includes full descriptions of two new structures that 
control the disposition of multiprocessing synchronization and record 
information regarding the members of the multiprocessing system: the 
spin lock data structure (SPL) and the per-CPU database structure (CPU). 


The ADPDISP macro, described in Appendix B, provides the ability to 
transfer control within a driver, based on a specified adapter characteristic. 
Such adapter characteristics include the presence of mapping registers, 
bus address size, and the capabilities of the data paths. You should 
replace most existing occurrences of the CPUDISP macro with ADPDISP. 


This manual now includes a separate part (Part III; Chapters 12 through 
18) that discusses hardware-related driver issues and other advanced 
topics. This structure allows the manual to more clearly and concisely 
explain the general coding concepts and requirements for all VMS drivers 
in Parts I and II. 


VMS Version 5.0 allows Q22 bus systems to enable multilevel device 
interrupt dispatching. Section 12.3.4 describes this new feature as well as 
VMS interrupt dispatching in general. 


New and Changed Features 


VMS Version 5.0 allows Q22 bus device drivers to allocate sets of registers 
from the entire set of 8,192 map registers. Appendix C describes the 
following routines that are used to allocate, request, load, and release 
these alternate map registers. These routines include: 


IOCSALOALTMAP, 
lIOC$ ALOALTMAPN, 
lOC$ ALOALTMAPSP 


lIOCSLOADALTMAP 
lIOCSRELALTMAP 
lOCSREQALTMAP 


Allocate a set of Q22 bus alternate map registers 


Loads a set of Q22 bus alternate map registers 
Releases a set of Q22 bus alternate map registers 


Allocates sufficient Q22 bus alternate map 


registers to accommodate a DMA transfer and, 
if unavailable, place process in alternate-map- 
register wait queue 


The executive routines that perform buffer quota checking 
(EXES$BUFFRQUOTA and EXE$BUFQUOPRC) have beer. replaced in 
VMS Version 5.0 by similar routines that check and debit (or credit) a 
job’s byte count quota and, optionally, its byte count limit. Versions of 
these routines exist that also allocate a requested buffer. 


Appendix C includes discussions of the following buffer quota checking 


and adjusting routines: 


EXESCREDIT_BYTCNT, 
EXE$CREDIT_BYTCNT_BYTLM 


EXE$SDEBIT_BYTCNT(_NW), 
EXE$DEBIT_BYTCNT_BY TLM(_NW) 


EXE$DEBIT_BYTCNT_ALO, 
EXE$DEBIT_BYTCNT_BYTLM_ALO 


Return credit to a job’s buffered-|/O 
byte count quota and byte count 
limit 

Determine whether a job’s buffered 
1/O byte count quota usage 
permits the process to be granted 
additional buffered |/O and, if so, 
adjust the job’s byte count quota 
and byte count limit 


Determine whether a job’s buffered 
1/O byte count quota usage 
permits the process to be granted 
additional buffered 1/O and, if so, 
allocate the requested amount of 
nonpaged pool and adjust the job’s 
byte count quota and byte count 
limit 


Appendix C includes discussion of the following routines: 


ERLSDEVICEATTN 


Allocates an error message buffer and logs 


information relevant to an error that occurs on a 
device, independent of the !/O request currently 
being processed 


LDRSALLOC_PT 
LDRSDEALLOC_PT 


Allocates system page-table entries 
Deallocates system page-table entries 


The SYSGEN CONNECT and LOAD commands have been modified 
to load a driver image from either SYS$LOADABLE_IMAGES or 
SYS$SYSTEM. DIGITAL recommends that all drivers be placed in the 


SYS$LOADABLE_IMAGES directory. 
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This manual incorporates a description of the VMS terminal driver's 
class/port interface. Chapter 17 details this architecture and each of its 
vector entry points; Table A-20 and Figure A-21 illustrate the contents 
of the UCB terminal extension; and Appendix B describes the CLASS_ 
CTRL_INIT, CLASS_UNIT_INIT, $VEC, $VECINI, and $VECEND 
macros. : 


In VMS Version 5.0, the XDELTA entry IPL has become IPL 14 on all 
VAX processors. Formerly, it was IPL 5 on VAX uniprocessing systems 
and IPL 15 on VAX multiprocessing systems. 


The new BREAKPOINTS system parameter, by default, inserts a 
breakpoint at the end of system initialization. This is in addition to 

the breakpoint at the beginning of system initialization controlled by the 
boot flags described in Chapter 16. 


Special pool checking code has been added to the VMS memory 
allocation and deallocation routines to facilitate detection of pool 
corruption problems. You can enable this code to troubleshoot problems 
of this sort by setting the POOLCHECK system parameter, as discussed 
in Section 16.13. 


The VMS connect-to-interrupt facility, as detailed in Chapter 18, now 
supports UNIBUS device operations on the VAX 8200/8250/8300/8350 
and VAX 8530/8550/8700/8800 processors. 


Section 11.4 and Appendix D describe the role of a driver’s cloned UCB 
routine in I/O processing. 


Appendix A includes a description of all fields that have been added, 
moved, or modified since VMS Version 4.4. 


Other sections of this manual have been reorganized, corrected, and 
rewritten as necessary to accurately reflect VMS Version 5.0. 
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Introduction to Device Drivers 


Under the VMS operating system, a device driver is a set of routines and 
tables that the system uses to process an I/O request for a particular device 


type. 


The VMS operating system’s approach to I/O is that the system should 

- perform as much of the processing of an I/O request as possible and that 
drivers should restrict themselves to the device-specific aspects of I/O 
processing. To accomplish this, the VMS operating system provides drivers 
with the following services: 


e A Queue I/O request ($QIO) system service that preprocesses an I/O 
request by performing those functions and checks that are common to all 
devices; for example, validating those arguments of the I/O request that 
are not device specific 


¢ Many operating system routines that drivers can call to perform I/O 
preprocessing, allocate and deallocate resources, and synchronize driver 
execution 


¢ Macros that drivers can invoke to accomplish tasks that would otherwise 
require many lines of code 


e AVMSI/O postprocessing routine that performs device-independent I/O 
postprocessing for all 1/O requests 


Thus, drivers can leave the device-independent I/O processing to the 
operating system and concentrate on servicing those aspects of an I/O 
operation that vary from device type to device type. In addition, drivers can 
call VMS system routines to perform many functions that are common to 
several, but not all, devices. 


A device driver does not run sequentially from beginning to end. Rather, 
the operating system uses driver tables and other information maintained 
by itself and the driver to determine which driver routines to activate and 
when they should be activated. Because little sequential processing of driver 
code occurs, the VMS operating system must assume the responsibility for 
synchronizing the execution of the various driver routines, as well as the 
execution of all drivers in the system. A major purpose of this book is to 
describe the conventions that all VMS drivers must follow to maintain this 
synchronization and cooperate with the operating system in I/O request 
processing. 


This section first defines the general functions and purposes of a VMS device 
driver. It then introduces VMS concepts crucial to an understanding of how 
device drivers work within the operating system and integral to the process of 
successfully writing one. It concludes with a brief description of the flow of 
driver activity in servicing an I/O request, using the VMS line printer driver 
as an example. 
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1.2 
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Driver Functions 


A VMS device driver defines itself to the system procedure that loads the 
driver into system virtual address space and creates its associated data 
structures. Once loaded, a device driver controls I/O operations on a 
peripheral device by performing the following functions: 


¢ Defining the peripheral device for the rest of the operating system 


e Preparing a device unit and its controller (or both) for operation at system 
start-up and during recovery from a power failure 


e Performing device-dependent I/O preprocessing 


e Translating programmed requests for I/O operations into device-specific 
commands 


¢ Activating a device unit 

e¢ Responding to hardware interrupts generated by a device unit 
e¢ Responding to device timeout conditions 

e Responding to requests to cancel I/O on a device unit 

¢ Reporting device errors to an error logging program 


e Returning status from a device unit to the process that requested the I/O 
operation 





Driver Components 


Driver Tables 


Normally, a device driver module can consist of the routines and tables 
discussed in this section. With a few exceptions, which are noted throughout 
Chapter 6, the order of the various routines and tables within the driver 
module is not important. 


The following tables appear in every driver. 


The driver prologue table (DPT) defines the identity and size of the driver to 
the system routine that loads the driver into virtual memory and creates the 
associated data structures. With the information provided in the DPT, the 
driver-loading procedure can both load and reload drivers and perform the 
I/O database initialization that is appropriate to either situation. 


Section 6.1 describes the procedure for creating a DPT and further discusses 
its functions. Figure A-10 illustrates the DPT and Table A-9 describes its 
contents. 


The driver dispatch table (DDT) lists the addresses of the entry points of 
standard routines within the driver, and records the size of the diagnostic 
and error message buffers for drivers that perform error logging. You can 
find additional information and instructions on how to specify a DDT in 
Section 6.2. An illustration of the DDT appears in Figure A-9; Table A-8 
describes its contents. 


1.2.2 Driver Routines 


Introduction to Device Drivers 
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The function decision table (FDT) lists all valid function codes for the device, 
and associates valid codes with the addresses of I/O preprocessing routines, 
called FDT routines. The driver contains device-dependent FDT routines, and 
the VMS operating system itself provides routines (described in Section 7.5) 
that perform request preprocessing common to many I/O functions. 


When a user process calls the $QIO system service, the system service uses 
the I/O function code specified in the request to traverse the FDT and select 
one or more of these preprocessing routines for execution, as appropriate to 
the function. To prepare for the actual I/O operation, FDT routines perform 
such tasks as allocating buffers in system space, locking pages in memory, 
and validating the device-dependent arguments (p1 through p6) of the $QIO 
request. Section 6.3 provides further discussion of the FDT, and Chapter 7 
details strategies and rules for writing, specifying, and exiting from an FDT 
routine. 


In addition to any FDT routines it may contain, a device driver generally 
contains both a start-I/O routine and an interrupt service routine. 


The start-I/O routine performs such additional device-dependent tasks as 
translating the I/O function code into a device-specific command, storing 
the details of the user request in the device’s unit control block in the 
I/O database and, if necessary, obtaining access to controller and adapter 
resources. Whenever the start-I/O routine must wait for these resources 
to become available, the VMS operating system suspends the routine, 
reactivating it when the resources become free. 


The start-I/O routine ultimately activates the device by suitably loading the 
device’s registers. At this stage, the start-I[/O routine invokes a VMS macro 
that causes its execution to be suspended until the device completes the I/O 
operation and posts an interrupt to the processor. The start-I/O routine 
remains suspended until the driver’s interrupt service routine handles the 
interrupt. 


When a device posts an interrupt, its driver’s interrupt service routine 
determines whether the interrupt is expected or unexpected, and takes 
appropriate action. If the interrupt is expected, the interrupt service routine 
reactivates the driver’s start-I/O routine at the point of suspension. The 
general course of action of driver mainline code at this time is to perform 
device-dependent I/O postprocessing and to transfer control to the VMS 
operating system for device-independent I/O postprocessing. 


Details on writing a start-1/O routine appear in Chapter 8. A description of a 
driver interrupt service routine appears in Chapter 9. 


You can also include any of the following routines in a device driver. 


The unit initialization routine and controller initialization routine prepare a 
device or controller for operation when the VMS driver-loading procedure 
loads the driver into memory and when the VMS system recovers from a 
power failure. The amount and type of initialization needed by devices and 
controllers varies according to the device type and the I/O bus to which the 
device or controller is attached. Section 11.1 provides additional information 
about device driver initialization routines. 


1-3 


1.3 


1.3.1 


Introduction to Device Drivers 
1.2 Driver Components 


The I/O Database 


Driver Tables 


A timeout handling routine retries 1/O operations and performs other error 
handling when a device fails to complete a request in a reasonable period 
of time. Once every second, the VMS system timer checks all devices in 
the system for device timeout. When it locates a device that has timed out, 
because it is offline or some error has occurred, the system timer calls the 
driver’s timeout handling routine. 


Depending upon the reason for the timeout, the timeout handling routine 
may call a VMS error logging routine to allocate and fill an error message 
buffer with information about the error. In turn, the error logging routine can 
call a register dumping routine in the driver that also loads into the buffer the 
contents of device registers at the time of the error. 


Timeout handling routines are discussed in Section 10.2. Register dumping 
routines and driver error handling are discussed in Section 11.3. 


The VMS operating system calls a driver’s cancel-I/O routine when a user 
process issues a Cancel I/O on Channel ($CANCEL) system service for the 
device. It may also call the routine when the device’s reference count goes 
to zero, which occurs when all users with assigned channels to the device 
have deassigned them. The discussion of the cancel-I/O routine appears in 
Section 11.2. 





Because a driver and the operating system cooperate to process an I/O 
request, they must have a common and current source of information about 
the request. This is the function of the I/O database. Under the VMS 
operating system, the I/O database consists of these three parts: 


e Driver tables that allow the system to load drivers, validate device 
functions, and call driver routines at their entry points 


e Data structures that describe I/O bus adapters, device types, device units, 
device controllers, and logical paths from processes to a devices 


e I/O request packets that define individual requests for I/O activity 


Illustrations of I/O database structures and detailed descriptions of their fields 
appear in Appendix A. Figure 1-1 illustrates some of the relationships among 
VMS I/O routines, the I/O database, and a device driver. 


The three driver tables—driver prologue table, driver dispatch table, and 
function decision table—are defined in every driver. Section 1.2 lists these 
tables among the other components of a device driver, and Chapter 6 
discusses their contents. 


1.3.2 Data Structures 
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Figure 1-1 The I/O Database 
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I/O database data structures describe peripheral hardware and are used by 
the operating system to synchronize access to devices. VMS creates these 
data structures either at system startup or when a driver is loaded into the 
system. 


The system defines a unit control block (UCB) for each device unit attached 
to the system. A UCB defines the characteristics and current state of an 
individual device unit. 


UCBs are the focal point of the I/O database. When a driver is suspended 
or interrupted, the UCB keeps the context of the driver in a set of fields 
collectively known as a fork block.! In addition, the UCB contains the listhead 
for the queue of pending I/O request packets for the unit. 


A device data block (DDB) contains information common to all devices of the 
same type that are connected to a particular controller. It records the generic 
device name concatenated with the controller designator (for example, LPA, 
DBB), and the name and location of the associated device driver. In addition, 
the DDB contains a pointer to the first UCB for the device units attached to 
the controller. . 


" Other structures, such as the CRB, also include a fork block. The discussion of fork blocks and fork processes 
in Section 1.5 explains the role of fork blocks in driver processing. 
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The operating system creates a channel request block (CRB) for each controller. 
A CRB defines the current state of the controller and lists the devices waiting 
for the controller’s data channel. It also contains the code that dispatches a 
device interrupt to the interrupt service routine for that unit’s driver. 


The system also creates for each controller an interrupt dispatch block (IDB). 
An IDB lists the device units associated with a controller and points to the 
UCB of the device unit that the controller is currently servicing. In addition, 
an IDB points to device registers and the controller’s I/O adapter. 


An adapter control block (ADP) defines the characteristics and current state 
of an I/O adapter, such as the VAX UNIBUS and MASSBUS adapters, the 
Q22 bus interface of the MicroVAX 3600-series and MicroVAX II systems, 
or a device attached to the VAXBI bus. An ADP contains the queues and 
allocation bit maps necessary to allocate the adapter’s resources. VMS 
provides routines that drivers can call to interface with the appropriate 
adapter. 


The channel control block (CCB) describes the logical path between a process 


and the UCB of a specific device unit.2 Each process owns a number of CCBs. 
When a process issues the Assign I/O Channel (SASSIGN) system service, 
the system writes a description of the assigned device to the CCB. 


Unlike the data structures mentioned earlier, a CCB is not located in 
nonpaged system space, but in the process’s control region (P1 space). 


1.3.3 1/O Request Packets 


The third part of the I/O database is a set of I/O request packets. When a 
process requests I/O activity, the operating system constructs an I/O request 
packet (IRP), that describes the I/O request in a standard form. 


The IRP contains fields into which the system and driver I/O preprocessing 
routines can write information: for instance, the device-dependent arguments 
specified in the call to the $QIO system service. The packet also includes 
buffer addresses, a pointer to the target device, an I/O function code, and 
pointers to the I/O database. After preprocessing, the IRP can be queued to a 
list originating in the device’s UCB to await processing by the driver. 


When the device unit is free and the IRP is next in line to be processed on 
the unit, the system sends it to the device driver's start-I/O routine. The 
start-I/O routine uses the IRP as its source of detailed instructions about the 
operation to be performed. 


? Channel request blocks and channel control blocks are two separate data structures. To help distinguish 
the two, it may be helpful to think of the channel request block as the “controller request” block because it 
describes the hardware controller. In contrast, the channel control block helps manage the logical channel (the 
channel argument to the $ASSIGN and $QIO system services) by means of which a process and a device unit 
accomplish I/O operations. 
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Synchronization of Driver Activity 


Driver Context 


Device drivers and other kernel-mode code must maintain synchronization 
with other priority operating system activities. The term synchronization 
refers to the means by which such code accesses shared data in a consistent, 
orderly, and predictable fashion. Because there may be more than one 
processor active in a VMS system, system-level code must synchronize its 
actions with other code threads it may have preempted on the same (or local) 
processor, as well as with those that are active (or to be activated) on other 
processors in the system. The VMS operating system uses hardware and 
software interrupt priority levels (IPLs) to order system events on each local 
processor in a VAX system. The VAX hardware defines 32 interrupt priority 
levels (IPLs). The higher numbered IPLs (16 through 31) are reserved for 
hardware interrupts, such as those posted by devices. The VMS operating 
system uses the lower numbered IPLs (0 through 15). Code that executes at a 
higher IPL takes precedence over code that executes at a lower IPL. 


A driver, in concert with the operating system, ensures that it maintains 
system synchronization by performing certain activities and accessing certain 
data only at the appropriate IPL. In a VMS multiprocessing system, the driver 
extends the synchronization it achieves by executing locally at a given IPL 
by acquiring ownership of the spin lock associated with the operation it is 
performing. (IPL, spin locks, and other forms of synchronization in a VMS 
system are discussed fully in Chapter 3.) 





As indicated in Section 1.2.2, a driver may have several routines to which the 
VMS operating system may pass control in certain situations. The context in 
which any one routine receives control from VMS may differ substantially 
from that in which another receives control. It is essential that a driver 
routine not attempt to exceed the limitations of the context in which it 
executes. 


In general, context is characterized by the following factors: 
e¢ The current IPL of the executing processor 


e The IPL at which the thread of execution that resulted in the call to the 
driver began 


¢ The currently owned spin locks of the executing processor 
¢ The data structures available to the routine 


¢ Data available to the routine in registers, in data structure fields, and on 
the stack 


e The condition of the registers, data structure fields, and stack when the 
routine exits 


e The ability or inability to access process space 


A complete description of the context of each driver routine appears in 
Appendix D. The following are some general observations: 


e §=6©All device driver routines execute in kernel mode at an elevated IPL. 


¢ Only driver FDT routines execute within process context and can access 
process space (PO and P1). 
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e The majority of driver routines execute in interrupt (or system context): 
that is, in the sequence of execution that follows a processor’s grant of 
an interrupt request at a given IPL. Such code can refer only to system 
(SO) space. Moreover, it cannot incur exceptions, including page faults, 
without causing a fatal bugcheck. Code executing in interrupt context is 
serviced on the interrupt stack, and must synchronize its execution with 
other priority code threads by using IPLs, spin locks, and resource wait 
queues, all of which are described in Chapter 3. 


Most driver processing of an I/O request (before and after the device 
acknowledges the servicing of the request by requesting an interrupt from 
the processor) occurs at a fork IPL. This portion of driver code, which includes 
most of the start-I/O routine, is commonly known as the driver’s fork process. 


There are several instances in the processing of an I/O request when a 
driver fork process must suspend execution to wait for a resource or a device 
interrupt. To make the matter of saving and restoring fork process context 
as efficient as possible, the VMS operating system places a restriction on the 
context of a driver fork process, in addition to those that apply to any process 
in interrupt context. Fork context consists of the following: 


¢ Two general purpose registers (R3 and R4) 
¢ The program counter (PC) 


¢ A fork block (usually the unit control block, the address of which is 
presumed to be in R5 at the time of the suspension) that can contain 
additional fork process context 


VMS places the fork block of a suspended fork process in either a processor- 
specific fork queue or a resource wait queue where it waits to be resumed. 
When it resumes the fork process, VMS ensures that the fork context is 
restored. Fork blocks, fork processes, and fork queues are discussed fully in 
Section 3.3.3. 


1.5.1 Example of Driver Context-Switching 


Because a device driver consists of a number of routines that are activated by 
VMS, the operating system for the most part determines the context in which 
the routines execute. 


As an example, consider the following write request that occurs without error: 


1 A user process executing in user mode calls the $QIO system service to 
write data to a device. 


2 The $QIO system service gains control in process context but in kernel 
mode. It performs device-independent preprocessing of the I/O request. 


3 The system service uses the driver’s function decision table to call the 
appropriate FDT routines to perform device-dependent preprocessing. 
These FDT routines execute in full process context in kernel mode. 


4 When preprocessing is complete, a VMS routine creates a fork process to 
execute the driver’s start-I/O routine in kernel mode. 


5 The start-I/O routine activates the device unit and suspends itself. At this 
point, VMS suspends the fork process executing the start-I/O routine and 
saves sufficient context to reactivate the start-I/O routine at the point of 
suspension. 


Introduction to Device Drivers 
1.5 Driver Context 


6 When the device completes the data transfer, it requests an interrupt. 
The interrupt causes the system to activate the driver’s interrupt service 
routine. 


7 The interrupt service routine executes to handle the device interrupt. It 
then causes the start-I/O routine to resume in interrupt context. 


8 The start-I/O routine regains control in interrupt context but almost 
immediately issues a request to the operating system to transform its 
context to that of a fork process. This action dismisses the interrupt. 


9 When reactivated in fork process context, the start-I/O routine performs 
device-specific I/O completion and passes control to the system for 
additional I/O postprocessing. 


10 VMS I/O postprocessing runs in interrupt context at a lower IPL and 
issues a special kernel-mode asynchronous system trap (AST) for the user 
process requesting I/O. 


11 When the special kernel-mode AST is delivered, the AST routine executes 
in full process context in kernel mode to deliver data and status to the 
process. If the original request specified a user-mode AST, the special 
kernel-mode AST queues it. 


12 When the user process gains control, the user’s AST routine executes in 
full process context in user mode. 





1.6 Hardware Considerations 
The VMS operating system runs on any of the following VAX systems: 
¢ VAX 6200 series 
e =VAX 8530/8550/8700/8800/8830/8840 
e VAX 8600/8650/8670 
e VAX 8200/8250/8300/8350 
¢ = VAX-11/785 and VAX-11/780 
e VAX-11/750 
¢ = VAX-11/730 and VAX-11/725 
¢ MicroVAX 3600 series 
e VAXstation 2000/MicroVAX 2000 
¢ = MicroVAX II 
¢ = MicroVAX I 


Although these system configurations employ the same operating system 
and conform to the VAX architecture, there are some differences in design 
among the machines that merit consideration in device driver coding, 
installation, and debugging. For instance, VAX systems differ in the amount 
of available physical address space and in the location of device registers. 
Some VAX systems are available in multiprocessor configurations. Also, VAX 
systems support different and various combinations of I/O buses to which a 
nonstandard device can be connected. 
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If you follow the conventions described in this manual when writing your 
driver, your driver should, with little modification, drive the same device 
attached to a corresponding I/O bus of another VAX system. For specific 
system design and device configuration information, refer to your system’s 
technical reference or hardware manual or the VAX Hardware Handbook. 


1.6.1. Driver Dependency on VAX Processing Systems 


1.6.1.1 


This section outlines some of the general differences among the VAX 
processing systems that have a bearing upon the development of driver 
code. The main thrust of the discussion is to provide a brief summary of 
the layout of the I/O subsystems of the VAX processing systems, define a 
general terminology, and, when necessary, direct device driver writers to 
documentation particular to the I/O configuration of their device. 


VAX-11/780, VAX-—11/785, and VAX 8600/8650/8670 

The VAX-11/780, VAX-11/785, VAX 8600, VAX 8650, and VAX 8670 
systems, from the viewpoint of I/O architecture, are SBI-based systems. 
That is, the synchronous backplane interconnect (SBI) is the bus by which 
I/O adapters communicate with main memory and the central processor 
(see Figure 1-2). I/O adapters supported by the SBI include the UNIBUS 
adapter (UBA), MASSBUS adapter (MBA), and the DR780 interface adapter. 
Correspondingly, peripheral devices attach to either the UNIBUS, MASSBUS 
or DR32 device interconnect (DDI) of the DR780 adapter. Main memory 
shares the SBI with the I/O adapters on the VAX-11/780 and VAX-11/785. 
The VAX 8600, VAX 8650, and VAX 8670 employ a separate bus to which 
main memory is attached and can each be configured with up to two SBIs for 
I/O adapters. 


For these systems, nonstandard devices are commonly attached to the 
UNIBUS, although some nonstandard devices connect to the MASSBUS and 
DDI. The components of UNIBUS and MASSBUS drivers are nearly identical 
and the strategies for producing driver code are similar; writers of either type 
of driver will profit from reading the bulk of this manual. Writers of UNIBUS 
drivers can find specific information about the UNIBUS adapter and VMS 
support for UNIBUS drivers in Chapter 12. MASSBUS driver writers should 
refer to Chapter 13 for similar information about the MASSBUS. DIGITAL 
supplies a device driver and an application library for DDI devices; the VMS 
I/O User’s Reference Manual: Part II discusses the DR32 interface driver in 
detail. 


A final note on terminology regarding these systems is pertinent. For the 
purposes of the discussion in this book, the term VAX-11/780 refers to the 
family of VAX systems that includes the VAX-11/780 and VAX-11/785; the 
term VAX 8600 refers to the VAX 8600, VAX 8650, and VAX 8670. 


1.6.1.2 
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Figure 1-2 SBI-Based System Configurations 
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VAX-11/750 

The VAX-11/750 system resembles the VAX-11/780-type systems in that it 
supports UNIBUS, MASSBUS, and DDI peripheral devices (see Figure 1-2). 
The backplane, or CPU-to-memory interconnect (CMI), by which I/O 
adapters communicate with the central processor and main memory, is 
integral to the processor, as are the UNIBUS interface (UBI) and MASSBUS 
adapter (MBA). The DR750 interface adapter connects the CMI to the DDI 
subsystem. Peripheral devices connect to the UNIBUS, MASSBUS, and DDI. 
A separate memory interconnect provides an interface between main memory 
and the rest of the system. 


For the VAX-11/750, nonstandard devices are commonly connected to the 
UNIBUS, although some nonstandard devices attach to the MASSBUS. 

The components of UNIBUS and MASSBUS drivers are identical, and the 
strategies for developing driver code are similar. Writers of either type of 
driver will profit from reading this manual. Writers of UNIBUS drivers can 
find specific information about the UNIBUS adapter and VMS support for 
UNIBUS drivers in Chapter 12. MASSBUS driver writers should refer to 
Chapter 13 for similar information about the MASSBUS. DIGITAL supplies a 
device driver and an application library for DDI devices device; the VMS I/O 
User’s Reference Manual: Part II discusses the DR32 interface driver in detail. 


1-11 


Introduction to Device Drivers 
1.6 Hardware Considerations 


1.6.1.3 


1.6.1.4 


VAX-—11/730 and VAX-—11/725 

The VAX-11/730 and VAX-11/725 systems, like the VAX-11/750, 
incorporate an integral UNIBUS adapter to control transactions between 
UNIBUS peripheral devices, the processor, and the main memory interface. 
The VAX-11/730 and VAX-11/725, however, do not support MASSBUS 
devices. Writers of UNIBUS drivers can find specific information about the 
UNIBUS adapter and VMS support for UNIBUS drivers in Chapter 12. For 
the purposes of the discussion in this book, the term VAX-11/730 refers to 
both the VAX-11/730 and the VAX-11/725. 


- VAX 8200/8250/8300/8350, 


VAX 8530/8550/8700/8800/8830/8840, and VAX 6200 Series 
The VAX 8200/8250/8300/8350, VAX 8530/8550/8700/8800/8830/8840 
and VAX 6200 series are VAXBI-based systems; that is, the VAXBI is the bus 
by which I/O adapters communicate with main memory and the central 
processor (see Figure 1-3). 


In a VAX 8200/8250/8300/8350 configuration, main memory, the DWBUA, 
and other devices are all connected directly to the VAXBI bus. By contrast, the 
VAX 8530/8550/8700/8800/8830/8840 and VAX 6200-series configurations 
employ separate memory interconnects (known as the NMI, PBI, or XMI, as 
illustrated in Figure 1-3, to service main memory. The VAX 8530/8550/ ; 
8700/8800 provides multiple VAXBI buses to which I/O adapters and devices 
can be attached. The VAX 8300, VAX 8350, VAX 8800/8830/8840, and VAX 
6200 series are multiprocessor systems. 


The VAXBI bus supports UNIBUS peripherals by means of the BI-to- 
UNIBUS adapter (DWBUA). Writers of UNIBUS drivers can find specific 
information about the UNIBUS adapter and VMS support for UNIBUS drivers 
in Chapter 12. 


The VAXBI also supports non-DIGITAL-supplied devices designed according 
to specifications established by DIGITAL and a license granted by DIGITAL. 
Writers of drivers for such devices, referred to as generic VAXBI devices in this 
manual, can find specific discussion in Chapter 14. . 


A final note on terminology regarding these systems is pertinent. For the 
purposes of the discussion in this book, the term UNIBUS adapter includes the 
DWBUA, and the term backplane interconnect represents the VAXBI bus. 
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Figure 1-3 VAXBI-Based System Configurations 
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Figure 1-3 (Cont.) VAXBI-Based System Configurations 
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1.6.1.5 MicroVAX 3600 Series and MicroVAxX II 
The MicroVAX 3600 series and MicroVAX II are Q22 bus-based systems. 
On these systems, the Q22 bus is the bus by which peripheral devices 
communicate with main memory and the processor.? Q22 bus device drivers 
are sufficiently similar to those that drive UNIBUS devices that most of the 
discussion of UNIBUS drivers in this book can equally pertain to the writing 
of Q22 bus device drivers (see Chapter 12 for a discussion of the similarities 
and differences). 


As you can see in Figure 1-4, in these systems main memory and I/O devices 
reside on separate interconnects. The MicroVAX 3600-series and MicroVAX 
II systems implement a scatter-gather map containing 8,192 map registers 
that allows devices to perform multiple-block direct-memory-access (DMA) 


transfers.4 


For the purposes of discussion in this manual, the term backplane interconnect 
represents the Q22 bus in the MicroVAX 3600-series and MicroVAX II 
systems. The term Q22 bus interface represents those functions performed 

by these processors that resemble those performed by the UNIBUS adapter of 
other VAX systems. In most instances, you can assume that discussions of the 
UNIBUS adapter apply as well to the Q22 bus. 


Figure 1—4 MicroVAX 3600-Series and MicroVAX II System 
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> DMA controllers attached to the Q22 bus must be capable of 22-bit addressing. 

* In these systems, the 4MB of Q22 bus memory is located from physical address 30000000;, to 303F000016. If 
you must install controllers that contain local memory on the Q22 bus, it is best to install them in the upper 
3 3/4 MB of Q22 bus memory (after physical address 30040000;,). The first 1/4 MB of Q22 bus memory 
contains 496 map registers, 127 of which must be free for use by VMS in booting. If you must place a 
controller containing memory in this address region, it cannot occupy more than 369 pages. If the controller 
exceeds this space, VMS will probably boot but will not be able to take crash dumps. 
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1.6.1.6 MicroVAX | 
The MicroVAX I is a Q22 bus-based system; that is, the Q22 bus is the bus by 
which peripheral devices communicate with main memory and the processor. 
Q22 bus device drivers are sufficiently similar to those that drive UNIBUS 
devices that most of the discussion of UNIBUS drivers in this book can 
equally pertain to the writing of Q22 bus device drivers (see Chapter 12 for a 
discussion of the similarities and differences). 


MicroVAX I main memory and I/O devices exist together on the same bus 
(see Figure 1-5). The effects of the absence of a scatter-gather map on DMA 


device drivers are discussed in Section 12.2.8.° 


Figure 1-5 MicroVAX | System Configuration 
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1.7 Programmed-!|/O and Direct-Memory-Access Transfers 


Devices are equipped with various registers that initiate, control, and monitor 
the progress of data transfer, seek operation, or other requests for device 
activity. When it completes a request, the device posts an interrupt to the 
processor. The size of the transfer concluded by a device interrupt depends 
upon the capabilities of the device. 


° The MicroVAX I uses the 22-bit Q22 bus to address both main memory and Q22 bus memory. Because 
MicroVAX I main memory shares the Q22 bus with I/O devices, the maximum amount of address space 
available for main memory (4MB at most) is correspondingly decreased whenever controllers containing 
memory are attached to the Q22 bus. For instance, if a controller containing a 256K bit map is installed on 
the Q22 bus, 3 3/4 MB would remain for main memory. VMS is effectively prevented from using as main 
memory those locations addressable as controller memory by the appropriate setting of the PHYSICALPAGES 
system parameter. In the preceding example, PHYSICALPAGES would be set to 7680 to prevent the double 
mapping of the 256K bit map as both main memory and controller memory. 
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Programmed I/O 


Drivers for relatively slow devices, such as printers, card readers, terminals, 
and some disk and tape drives, must transfer data to a device register a 
byte or a word at a time. These drivers must themselves keep a record of 
the location of the data buffer in memory, as well as a running count of 
the amount of data that has been transferred to or from the device. Thus, 
these devices perform programmed I/O (PIO) in that the transfer is largely 
conducted by the driver program. 


Examples of UNIBUS devices that do PIO transfers are the LP11 and the 
DZ11. Corresponding Q22 bus devices that perform PIO transfers are the 
LPV11 and the DZV11. 


Chapter 2 outlines the action of the LP11 driver. The LP11 driver transfers 
data from a system buffer to the line printer data buffer register a byte at 

a time, while maintaining a count of the number of bytes left to transfer. 
When the line printer data buffer is full, the line printer sets a “not ready” 
bit in its status register. If the driver, while examining this register, sees this 
bit set, it enables interrupts from the printer, and then suspends itself in the 
expectation that the printer will post an interrupt to the processor. While 
the driver remains suspended, the printer prints the data from its buffer and 
interrupts the processor when it is done. With the interrupt handled by the 
system interrupt dispatcher and the driver interrupt service routine, driver 
execution resumes. The driver repeats both its byte-by-byte transfer to the 
printer data buffer, as well as the entire routine described previously, until it 
determines that all the data has been transferred as requested. 


Drivers performing PIO transfers are generally not concerned with the 
operation of I/O adapters. However, drivers that perform direct-memory- 
access (DMA) transfers must take into account I/O adapter functions, as 
discussed in Section 1.7.2. 


1.7.2 Direct-Memory-Access I/O 


Devices that perform direct-memory-access (DMA) transfers do not require 
the central processor so frequently. Once the driver activates the device, the 
device can transfer a large amount of data without requesting an interrupt 
after each of the smaller amounts. The responsibilities of a driver fora DMA 
device involve supplying a device register with the starting address of the 
buffer containing the data to be transferred, a byte offset into the buffer, and 
the size of the transfer. By setting the appropriate bit or bits in the device 
control and status register (CSR), the driver activates the device. The device 
then automatically transfers the specified amount of data to or from the 
specified address. The VMS drivers DLDRIVER and XADRIVER are examples 
of DMA drivers, and appear in full in Appendixes E and F, respectively. 


For DMA transfers, UNIBUS drivers and MicroVAX 3600-series /MicroVAX II 
drivers must first map the transfer from main memory to I/O bus memory 
space. The result of this mapping is a set of contiguous addresses in UNIBUS 
or Q22 bus space that the DMA device can access to successfully perform a 
DMaA transfer. To accomplish this, a driver must first obtain map registers, 
and, optionally for UNIBUS drivers, a buffered data path. The driver calls 
VMS routines that interface with the I/O adapter to allocate these resources 
on behalf of the driver. Chapter 12 discusses the operation of the UNIBUS 
adapter and the Q22 bus. Section 12.2 provides instructions on how to write 
a DMA driver for UNIBUS and Q22 bus devices. 
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The MicroVAX I Q22 bus has no map registers, so no mapping of physical 
bus addresses to virtual memory addresses is possible. As a result, a driver 
for a device attached to the MicroVAX I Q22 bus that performs DMA transfers 
must include special logic that either allocates a physically contiguous buffer 
from nonpaged pool for use in the transfer or segments the transfer at page 
boundaries. Section 12.2.8 discusses the strategies for producing MicroVAX I 
DMA drivers. 


Some controllers that can do DMA transfers on the Q22 bus have microcode 
that allows the controller itself to do physical-to-virtual address mapping. 
This allows such controllers to do scatter-gather mapping, eliminating the 
need for transfers to be made to or from physically contiguous main memory. 
The RD/RX controller, which MicroVAX I uses for its system disk, is such a 
controller. 


The method by which a generic VAXBI device capable of DMA transfers 
accomplishes such a transfer depends upon the characteristics of the device. 
Several methods are discussed in Section 14.5. 





1.8 Buffered and Direct I/O 


A separate issue, but one related to the data transfer capabilities of a device, 
results from the fact that the original buffer, as specified in the user $QIO 
request, is in process space and is mapped by process page-table entries. 
Because the driver cannot rely on process context existing at the time the 
device is ready to service the I/O request, it must have some means of 
guaranteeing that it can access both the data involved in the transfer and the 
page-table entries that map the buffer. 


The VMS operating system provides the following two techniques that are 
employed by device drivers: 


e Direct I/O, the technique used most commonly by drivers of DMA 
devices, locks the user buffer in memory as well as the page-table entries 
that map it. The function decision table (FDT) of such a driver calls a 
VMS-supplied FDT routine that prepares the user buffer for direct I/O. 


e Buffered I/O is the strategy whereby the driver FDT dispatches to an FDT 
routine in the driver that allocates a buffer from nonpaged pool. It is 
this intermediate buffer that is involved in the transfer. The driver later 
refers to the buffer using addresses in system space. Driver preprocessing 
routines copy the data from the user buffer to the system buffer for a 
write request; VMS I/O postprocessing (by means of a special kernel- 
mode AST) delivers data from the system buffer to the user buffer for a 
read request. Drivers most often use buffered I/O for PIO devices such 
as line printers and card readers. 


The trade-off between buffered I/O and direct I/O is the time required to 
move the data into the user’s buffer as against the time required to lock 
the buffer pages in memory. Sections 6.3.1 and 7.4 provide additional 
information. 
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Figure 1-6 illustrates how the VMS operating system and the device driver 
process a user request for a read I/O operation for a DMA device attached to 
a UNIBUS or Q22 bus. 


Figure 1-6 Example of I/O Request Processing 
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processing of the sample I/O request illustrated in Figure 1-6 occurs in 
following steps: 


A process requests an I/O operation. 


A user process initiates an I/O request by issuing either a $QIO system 
service call or an RMS call resulting in a call to the $QIO system service. 


The user process specifies the target device, a read function code, and the 
address of a buffer into which the data is to be read. 


The operating system performs I/O preprocessing. 


The $QIO system service validates the request and locates data structures 
in the I/O database that describe the device and its driver. The system 
service also allocates and initializes an I/O request packet to contain a 
description of the I/O request. The system service then calls a reading 
routine in the driver. 


The driver performs I/O preprocessing. 


The driver FDT routine verifies that the user buffer resides in virtual 
memory pages that can be modified by the requesting process, locks the 
buffer pages in memory, and adds details of the I/O operation to the I/O 
request packet. The read FDT routine then calls the operating system to 
send the I/O request packet to the driver. 


VMS creates a driver’s fork process. 


A VMS routine creates a fork process in which the device driver can 
execute. The routine activates the driver’s fork process by transferring 
control to the driver’s start-I/O routine. 
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5 The driver readies the I/O adapter. 


For DMA transfers, the driver’s fork process calls VMS routines that 
enable the I/O adapter hardware to map I/O bus addresses into physical 
addresses for the transfer. (Note that the MicroVAX I system does not 
have this capability, as discussed in Section 12.2.8.) 


6 The driver activates the device. 
The fork process activates the device by setting bits in device registers. 
7 The driver waits for an interrupt. 


A VMS routine saves the context of the driver’s fork process and 
relinquishes the processor until an interrupt occurs. 


8 The device requests an interrupt. 


When the data transfer is complete, the device requests a hardware 
interrupt that causes the system to dispatch to the driver’s interrupt 
service routine. 


9 The driver services the interrupt. 


The driver's interrupt service routine handles the interrupt and reactivates 
the driver, which reads device registers to obtain status information about 
the transfer. 


10 The operating system inserts the driver in a fork queue. 


The driver requests that it again be suspended, to be reactivated later at a 
lower software IPL. 


11 The fork dispatcher reactivates the driver’s fork process. 


When processor priority permits, the VMS fork dispatcher reactivates the 
driver as a fork process. 


12 The driver completes the I/O operation. 


The driver’s fork process completes device-dependent processing of the 
I/O request and returns the I/O status to VMS. 


13 VMS completes the I/O operation. 


The VMS I/O postprocessing routines copy the I/O status into process 
address space, general registers, or both, and return control to the user 
process. 


Only four of these 13 steps describe the driver’s I/O preprocessing and fork 
processing. The VMS I/O-support routines perform I/O processing common 
to many I/O requests. Driver writing is further simplified by the use of VMS 
routines that handle device-independent functions. 
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The preceding example simplifies the processing of an I/O operation by 
ignoring such issues as 


The association of a device with a process, which is to say device 
assignment 


Simultaneous I/O requests for one device 

System synchronization issues, such as IPLs and spin locks 
Driver competition for shared system and I/O adapter resources 
Driver competition for a multiunit controller 


Driver recovery from device errors or power failure 


Subsequent chapters discuss each of these issues in relation to device drivers. 
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2 Discussion of a $Q10 Request 


This chapter outlines the series of activities performed by the VMS operating 
system and a simple device driver in order to process an I/O request. The 
LP11 line printer driver (LPDRIVER) was selected for this discussion because 
it is a simple driver but still illustrates many driver principles. The first-time 
reader of this document might not understand all of the points made in this 
chapter; however, the chapter should provide some insight into driver flow 
and I/O processing. 


The LP11 printer is a PIO device (see Section 1.7.1). Although the LP11 is 
usually spooled, this discussion assumes that it is not. 


A user process can request the following functions on this printer: 
e Write data to the printer 
¢ Read the printer’s device characteristics 


e Alter the printer’s device characteristics 


This chapter describes two aspects of printer I/O processing: 


¢ The portions of the line printer driver that are used in servicing a write 
request 


¢ The VMS components with which the driver interacts to process the write 
request 


Figure 2-1 illustrates the flow of execution through the VMS executive 
routines and printer driver code that satisfies an I/O request. The unshaded 
boxes in Figure 2-1 indicate the processing performed by driver subroutines. 
Boxes shown above the solid line indicate processing in the context of the 
user process. Boxes below the line indicate processing in fork or interrupt 
context. 





2.1 Driver Code for the LP11 Write Function 


The VMS device driver for an LP11 printer implements a write function using 
the following parts of the driver: 


e An FDT routine that reformats the user-supplied data 


¢ A start-I/O routine that writes data to the printer data buffer register until 
the printer enters a busy state as it prints the contents of its internal print 
silo 


¢ Code that modifies a device register to enable interrupts from the printer 


e An interrupt service routine that returns control to the driver’s fork 
process after a hardware interrupt from the printer 


¢ Code that returns I/O status to a VMS I/O completion routine 


2.2 
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Figure 2-1 A Printer Write Function 
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A User Process’s I/O Request 


A user process writes a line to the printer by calling the Queue I/O Request 
(SQIO) system service, specifying the write-virtual-block function code as 
follows: 


$QIO_S chan = CHANNEL_NUMBER, - 
func = #10$_WRITEVBLK, - 
efn = #6,- 
iosb = STATUS_BLOCK, - 


pi = BUFFER_ADDRESS, - 
p2 = #BUFFER_SIZE, - 
p4 = #°X30 


Note that p1, p2, and p4 are device-dependent arguments. 
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2.3 Device-Independent I/O Preprocessing by VMS 


The $QIO system service first validates that the I/O request is correctly 
specified. The I/O request must meet the following criteria: 


¢ The location CHANNEL—NUMBER must contain a number that serves as 
a valid index into the process’s channel list. This means that the process 
must have previously assigned the printer to this process channel using 
the Assign I/O Channel system service. Once $QIO locates the assigned 
channel control block, it can retrieve the address of the unit control 
block (UCB) of the target device of the request. Ultimately, it obtains the 
address of the driver’s function decision table (FDT), by way of a chain of 
longword pointers within the I/O database: 


CCB — UCB — DDT — FDT 


e The driver FDT must list IO$_WRITEVBLK as a valid function for the 
device. 


e The event flag number must be valid. 


e The process’s remaining buffered I/O count (BIOCNT) must permit the 
$QIO system service to perform a buffered-I/O request. 


e The process must have write access to location STATUS_BLOCK, 
specified in the request for use as an I/O status block. 


If all of these checks succeed, the $QIO system service creates an I /O request 
packet (IRP) in nonpaged system address space. The service then writes all 
known details about the I/O request into the IRP. 


If the target device for the I/O request is not file structured, the $QIO system 
service changes any virtual-function code to its equivalent logical-function 
code when it builds the IRP. Thus, for a printer device, IO$_.WRITEVBLK is 
translated to IO$_WRITELBLK. 





2.4 Device-Dependent I/O Preprocessing by the Driver 


Once it has validated the I/O request, the $QIO system service scans the FDT 
for an entry that associates the IO$_WRITELBLK function code with an FDT 

routine. The system service calls the routine, which in the case of the printer 
driver is a device-specific routine located in the printer device driver. 


The FDT routine confirms that the requesting process has read access to the 
buffer starting at BUFFER_ADDRESS. Then, the FDT routine buffers data 
from the process address space into system address space in the following 
steps: 


e It calculates the length of the required system space buffer. 


e If the job byte count quota for buffered I/O (JIB$L_BYTCNT) permits, 
the routine allocates a buffer from system address space, stores the 
address of the buffer in the IRP, and decreases the current job byte count 
quota. 


e It then synchronizes access to the printer’s UCB by obtaining its mutex 
(UCB$L_LP_MUTEX) for write access. It can thus reliably preprocess the 
write request, depending upon information contained in the UCB. 
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By obtaining the line printer mutex, the driver FDT routine effectively 
prevents processes active in a VMS multiprocessing system from initiating 
simultaneous functions on the printer. Also, in a VMS uniprocessing 
system, this action prevents contention between a process that has 
allocated the printer (and has been preempted in the midst of a write 
function) and any of its subprocesses that, when scheduled, may attempt 
to start a concurrent function that alters device characteristics. 


e It reads the description of the printer’s current line and page position 
from the device’s UCB. 


e It reformats the data from the process buffer into the system buffer, 
adding carriage control characters, as specified in argument p4 to the I/O 
request, before and after the data. 


Formatting includes such functions as the replacement of horizontal tabs 
with multiple spaces and the replacement of lowercase characters with 
uppercase characters, if necessary. 


e It rewrites updated line and page positions into the device’s UCB. This 
information indicates what the current location on the page being printed 
will be when the request completes. 


e Finally, the routine transfers control to a VMS routine that queues the IRP 
to the device driver. 


All of the I/O processing described to this point occurs in the context of 

the user’s process. The user address space is mapped, and the processor’s 
IPL is still low enough to permit process scheduling and paging. Subsequent 
queuing of the transfer request to the driver and all resulting driver processing 
occur at higher IPLs—and with ownership of the appropriate fork lock and 
device lock in a VMS multiprocessing environment—that synchronize the 
driver’s handling of the device. (See Chapter 3 for a discussion of the concept 
of synchronization.) 





2.5 Queuing the I/O Request Packet to the Driver 


Before queuing the IRP to the printer driver, the VMS queuing routine raises 
the IPL to the driver’s fork level and obtains the associated fork lock in a 
VMS multiprocessing environment. These actions synchronize access to those 
fields of the UCB referenced by driver routines at fork IPL. 


If the device is idle, which is to say that if the busy bit in the UCB status 
longword (UCB$V_BSY in UCB$L_STS) of the UCB is clear, VMS can 
transfer control to the driver. The driver dispatch table (DDT) contains the 
entry point to the driver’s start-I/O routine. To find the proper entry point, 
the queuing routine chains through the I/O database to the DDT, as follows: 


UCB — DDT -— start-I/O routine 


If the device unit is busy with another transfer, VMS inserts the IRP in a 
queue of packets waiting for the unit. The UCB contains the head of the 
queue. The packet’s position in the queue depends on the scheduling priority 
of the process issuing the request. 
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2.6 Activating the Printer 


The LP11 printer controller accepts data into an internal print silo until the 
silo is full or the driver writes a carriage-control character to the printer’s 
data buffer register. When either event occurs, the printer sets a busy bit in 
the device’s control and status register (CSR). Then the device driver sets the 
interrupt-enable bit in the device’s CSR and waits for the printer to interrupt. 
When the printer requests a hardware interrupt, the driver can resume writing 
characters to the printer’s data buffer register. 


The driver routine delivers characters to the printer according to the following 
sequence: 


1 The driver locates the LP11 device registers using a chain of pointers 
starting at the device’s UCB. 


UCB — CRB — IDB — CSR address 


The CSR address is always the address of the printer’s CSR, and all 
other device registers are at fixed offsets from this address. In contrast 
to many other devices, such as disks, the LP11 printer does not share a 
controller with other devices; therefore, no arbitration for ownership of 
the controller is required. 


2 The driver examines the device’s CSR to see if the device is ready to 
accept characters. 


3 If the device is ready, the driver writes a byte of data to the printer’s data 
buffer register. The printer controller moves the byte from the register to 
the controller’s internal print silo. 


4 The driver decreases the count of bytes to transfer and repeats step 2. ° 


5 If the device is not ready (that is, its print silo is full), the driver raises 
IPL to device IPL and obtains the corresponding device lock in a VMS 
multiprocessing system. These actions allow it to set the interrupt-enable 
bit in the device’s CSR in synchronization with other routines in the 
driver that may access the CSR. 


After setting the interrupt-enable bit, the driver invokes a VMS wait-for- 
interrupt macro to release the device lock and suspend driver processing 
until the printer requests an interrupt or the device times out. 





2.7 Waiting for a Device Interrupt 


The VMS wait-for-interrupt routine suspends the driver by performing the 
following functions: — 


e Saving driver context (R3, R4, and the address of the next instruction in 
the driver) in the device’s UCB 


¢ Calculating the time at which the device will time out 


e Setting bits in the device’s UCB to indicate that the driver expects a device 
interrupt within a specified time period 


e Releasing the device lock in a VMS multiprocessing system, restoring IPL 
to fork level, and returning control to the caller of the driver’s start-I/O 
routine . 
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The driver remains in a suspended state until one of two events occurs: 
e The printer requests a hardware interrupt. 


e VMS reports a device timeout because the printer did not request a 
hardware interrupt within a specified period of time. 


Normally, the LP11 prints the contents of its data buffer and requests the 
interrupt. 





2.8 Handling Interrupts 
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When the LP11 printer requests a hardware interrupt, the interrupt dispatcher 
passes the interrupt to the LP11 driver’s interrupt service routine. 


The driver’s interrupt service routine restores control to the driver, as follows: 
1 Restores the address of the UCB in R5 


2 Obtains the appropriate device lock to ensure synchronization in a VMS 
multiprocessing environment 


3 Confirms that the interrupt was expected by examining bits in the device’s 
UCB 


4 Restores the saved registers (R3 and R4) from the device’s UCB 


5 Transfers control to the driver PC address stored in the device’s UCB 


Rather than execute in interrupt context, the reactivated driver routine calls a 
VMS routine to create a fork process. As a result of this action, VMS again 
suspends driver processing by performing the following steps: 


1 Saving driver context (R3, R4, and the driver PC address) in the device’s 
UCB 


2 Inserting the UCB address in the appropriate fork queue in the local 
processor’s CPU database 


The driver suspension allows the operating system to reschedule driver 
processing at its fork IPL and permits higher priority code to execute and 
device interrupts to be serviced while driver processing of the I/O request 
concludes. The VMS fork dispatcher reactivates the driver when the IPL of 
the local processor drops to fork level. 


After creating the fork process, the system returns control to the driver’s 
interrupt service routine, which restores the registers saved at the time of the 
device interrupt, releases the device lock, and dismisses the interrupt. 
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2.9 |/O Postprocessing by the Driver 


When the VMS fork dispatcher reactivates the driver’s fork process, the 
driver obtains the number of characters left to transfer from the UCB. If there 
are still characters to transfer, the driver and printer repeat the procedures 
outlined in Sections 2.6 through 2.8, until the transfer is complete. When 
all characters have been transferred, the driver code branches to the driver's 
I/O-completion code. 


The driver’s I/O-completion code stores a success status code and the number 
of bytes transferred in RO, then transfers control to VMS to complete the I/O 
request. 





2.10 I/O Postprocessing by VMS 


The operating system inserts the IRP into the I/O postprocessing queue 

of the executing processor and requests an interrupt from the processor 

at IPL$_IOPOST. If another IRP is queued to the UCB for the device 

unit, VMS dequeues that packet and calls the driver start-I/O routine to 
process it. When IPL drops to IPL$_IOPOST, the processor grants the I/O 
postprocessing interrupt request. The I/O postprocessing dispatcher dequeues 
the packet for the printer I/O request and performs the following steps: 


1 Increases the use count (PHD$L_BIOCNT) of the process’s buffered I/O 
requests because the current operation is complete. The use count is 
maintained for accounting purposes. 


2 Decreases the process’s buffered I/O count (PCB$W_BIOCNT) to reflect a 
completed buffered I/O operation. This operation restores buffered-I/O 
quota to the process. 


Deallocates the system buffer used for the reformatted user data. 
Increases the job’s byte count quota. 


Sets an event flag to indicate that the I/O operation is complete. 


ou fk WwW 


Queues a special kernel-mode AST routine that will deallocate the IRP 
and stores I/O status in the user’s I/O status block. 


The user process determines when the I/O operation is complete by the 
setting of the event flag and/or the filling of the I/O status block, according 
to the method defined in the I/O request. The Queue I/O Request and Wait 
(S$QIOW) system service completes synchronously and returns control and 
status to the user process only after the I/O operation has been completed. 
The Synchronize (6SYNCH) system service waits for the completion of 

an I/O request, initiated by the $QIO system service, that completes 
asynchronously to user process activity. 


3 Synchronization of 1/O Request Processing 


Because a device driver executes as kernel-mode code, it can preempt core 
system tasks and access critical system data. As a result it must adhere to a 
set of rules that governs the priority of system activities and controls the flow 
of system events. These synchronization rules ensure that both the operating 
system and the device driver access memory in an orderly and consistent 
fashion. 


This chapter contains the following discussions: 


¢ Section 3.1 discusses the interrupt priority levels, focusing on those IPLs 
and interrupt service routines that participate in the processing of an 1/O 
request. It briefly examines the roles of the other IPLs in the operating 
system. Whether you are writing a driver for a VMS uniprocessor or 
multiprocessor environment, you must adhere to the synchronization 
rules discussed in this section. 


¢ Section 3.3 illustrates how system synchronization is maintained during 
the processing of an I/O request on any VAX system. As part of this 
discussion, this section describes the driver fork process and the activity of. 
forking. Finally, it examines the methods by which a driver synchronizes 
at fork level and device interrupt level. 


e Section 3.4 discusses the mechanism by which driver code stalls to wait 
for an available adapter or controller resource on any VAX system. 





3.1 Interrupt Priority Levels 


The VAX architecture defines 32 levels of hardware priority, called interrupt 
priority levels (IPLs). These IPLs govern the sequence of system events that 
occur on each processor in a VAX system. The higher-numbered IPLs (16 
through 31) are reserved for hardware interrupts, and the lower-numbered 
IPLs (1 through 15) are reserved for software interrupts. Most process-based 
software runs at IPL 0. 


The hardware IPLs (16 through 31) are used for device interrupts (IPLs 20 
through 23), interprocessor interrupts in a multiprocessing system, interval — 
timer interrupts, urgent conditions like power failure, and such serious errors 
as a machine check. Those IPLs that have a bearing on driver execution are 
discussed in Sections 3.1.2 and 3.1.3. For specific hardware IPL information, 
see your VAX system’s hardware documentation or the VAX Hardware 
Handbook. 


The software IPLs (1 through 15) are defined by VMS as illustrated in 
Table 3-1. 
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Table 3-1 


IPL 


N OO Oh BW DM = O 


13 
14 
15 


Symbolic Name 


IPL$_ASTDEL 
IPL$_RESCHED 
IPL$_IOPOST 


IPL$_QUEUEAST 
IPL$_TIMERFORK 


IPL$_SYNCH 


IPL$_MAILBOX 


IPL$_POOL 


IPLs Defined by VMS 


Use 


Execution of most process-based software 
Reserved 

Servicing of AST-delivery interrupts 
Servicing of scheduler interrupts 

Servicing of |/O-postprocessing interrupts 
Reserved 

Fork level processing for queuing ASTs 


Entry level for software timer interrupt 
servicing 


Synchronization of access to system 
databases in a uniprocessor system! 


Fork level processing for access to 
mailboxes 
Allocation of nonpaged pool 


Fork level processing for executing driver 
code 


Recalculation of quorum; cancellation of 
mount verification (IPC) 


Reserved 
Entry level for XDELTA debugger 
Reserved 


TIPL$_TIMER, IPL$_SCHED, IPL$_JIB, IPL$_MMG, IPL$_FILSYS, and IPL$_IOLOCKS8 are all 
synonyms for IPL$¢_SYNCH (see Table 3-3). 


Because a higher IPL takes precedence over a lower IPL, a routine executing 
at one IPL can block interrupts on a processor at that IPL and all lower IPLs. 
This scheme allows VMS to assign the higher IPLs to system activities that 
must be dispatched quickly and with little chance of interruption. In a general 
sense, each processor services interrupts according to the following priorities: 


e Power failure 


e Processor errors 


e Device interrupts 


e Device driver fork processing 


¢ 1/0 postprocessing 


¢ Process rescheduling 


e AST delivery 


As a result of blocking events on and ordering the activities of a single VAX 
processor, VMS use of IPLs ensures that kernel-mode code accesses data in 
memory in a cooperative and predictable manner. The mechanism by which 
synchronized access to data is ensured is twofold. First, VMS associates 

a given IPL with the access of one or more data structures or databases. 


3.1.1 


3.1.2 
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Secondly, VMS defines an ordered set of semaphores, called spin locks, that 
extend IPL synchronization throughout a VMS multiprocessing system. A 
processor must obtain one or more of these spin locks before executing any 
code thread that must make use of the resources the spin lock protects. Spin 
locks thus allow each processor in a VMS multiprocessing system to share 
common system data and block events systemwide. 


For example, consider a code thread running at IPL 8 that intends to access 
the memory management database. To do so, it raises IPL to IPL$_MMG. 
This action gives it the exclusive right to access the database from the 
local processor, effectively preventing access by other code threads on the 
same processor. After raising IPL, this code thread requests the memory 
management (MMG) spin lock. Ownership of the MMG spin lock gives the 
processor executing this thread the exclusive right to access the database 
systemwide, and bars access from any other code thread ee on any 
other processor in the VAX system. 


Although discussions in this book treat IPL and spin lock synchronization 
as conceptually separate tasks for a device driver, the set of VMS 
synchronization macros, described in Table 3-2, makes adjustment of IPL 
and disposition of spin locks appear as a single operation. 


A full description of spin locks appears in Section 3.2. 


Interrupt Service Routines 


VMS associates certain IPLs with the execution of certain tasks. Moreover, 
when a processor in a VAX system grants an interrupt at a given IPL, the 
grant actually triggers the execution of a specific piece of code, called an 
interrupt service routine, that performs the task. 


Device drivers themselves contain an interrupt service routine which handles 
device interrupts at an appropriate device IPL (IPLs 20 through 23). In 
addition, drivers rely heavily upon-the VMS interrupt service routine known 
as the fork dispatcher which runs at several IPLs, including driver fork IPLs 8 
through 11. When the local processor’s IPL drops to fork IPL, it is the fork 
dispatcher that restores the context of the driver fork process and places it 
into execution. (See Section 3.1.2.4 and 3.3.2 for discussions of the device 
IPLs and interrupt dispatching, respectively. Sections 3.1.2.3 and 3.3.3 discuss 
the fork IPLs and driver fork processes.) 


IPL Use During I/O Processing 


The activities essential to the processing of an I/O request occur only at 
certain IPLs. VMS performs some of these tasks in system routines and 
interrupt service routines; drivers perform others. This section describes those 
IPLs and interrupt service routines that are most involved in I/O processing. 
Section 3.1.3 discusses the IPLs at which other system activities transpire 
that may influence the coding of a driver. For additional information on the 
pattern of synchronization throughout the servicing of an I/O request, see 
Section 3.3. 
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3.1.2.1 


3.1.2.2 


IPL 2 (IPL$_ASTDEL) 
The asynchronous system trap (AST) delivery interrupt service routine 
(SCH$ASTDEL) is associated with IPL$_ASTDEL. 


When an AST is specified for delivery to a process, the AST queuing routine 
(SCH$QAST) queues the AST to the specified process’s process control 


block (PCB).! When an AST is delivered is determined by the mode of 
the AST, the current mode of the processor, and the mode contained in 
the processor’s ASTLVL register. The VAX hardware, by means of the REI 
instruction, requests a software interrupt on the local processor at IPL$_ 
ASTDEL whenever the processor’s mode becomes less privileged than that 
specified as its ASTLVL.* 


The AST delivery interrupt service routine gains control when the processor's 
IPL drops below IPL$_ASTDEL, and delivers all deliverable ASTs to the 
currently scheduled process. Any code executing at IPL$_ASTDEL or higher 
blocks the execution of this interrupt service routine. 


To block the delivery of ASTs—specifically the kernel-mode AST that causes 
process deletion—I/O preprocessing, from the time that the $QIO system 
service allocates an IRP through the execution of the last FDT routine, occurs 
at IPLs no lower than IPL$__ASTDEL. The VMS allocation routine records the 
address of the system memory allocated for the IRP in a process register; if an 
AST that deletes the process were to occur, the allocated memory would be 
lost from the pool. 


In addition, some I/O postprocessing occurs in a special kernel-mode 

AST servicing routine that also executes at IPL$_ASTDEL. The special 
kernel-mode AST, running in the context of a process whose I/O has been 
completed, writes status information into an I/O status block, copies buffered 
input into process space, and deallocates system buffers. The completion of 
these tasks depends on the availability of process context. 


Page faults may be taken by code that executes at IPL$_ASTDEL. However, 
this is not the case with code executing at higher IPLs. Thus, programs that 
are sensitive to the contents of pageable data structures run at IPL$_ASTDEL 
to take page faults. For example, the allocation of paged pool is one such 
program code thread; paged pool, as a result, is protected by a mutex. 


IPL 4 (IPLS_IOPOST) 

The IPL$_IOPOST interrupt service routine (IOC$IOPOST) performs device- 
independent postprocessing of an I/O request. As appropriate to the 

I/O request, it adjusts process quota use and deallocates system memory. 
IOC$IOPOST also queues a special kernel-mode AST to the process’s PCB 
that, once process context is restored, writes status and data into the process’s 
address space. 


After it has completed whatever device-dependent postprocessing is required, 
a driver fork process requests I/O postprocessing by calling a VMS routine 
(COM$POST) that inserts an IRP in the local processor’s postprocessing 
queue (at CPU$L _PSBL) and requests a software interrupt at IPL$_IOPOST. 
When IPL drops below IPL 4, the IPL$_IOPOST interrupt service routine 


' Because the VMS AST queuing and delivery routines access the scheduler database, they synchronize within a 
VMS multiprocessing environment by obtaining the SCHED spin lock before modifying system data. 

2 In the event that a processor queues an AST to a process currently executing on another processor in a 
multiprocessing system, the local processor Benicia an interprocessor interrupt to the other processor to 


change its ASTLVL. 
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dequeues an IRP from the I/O postprocessing queue at CPU$L_PSFL, 
performs all I/O-completion tasks that can occur without reference to the 
device’s unit control block (UCB) and, thus, at an IPL lower than fork IPL. 


I/O postprocessing runs at an IPL higher than IPL$_RESCHED so that all 
pending I/O-completion processing is finished before the scheduler looks for 
a new process to schedule. The ability of a process to execute can depend on 
the completion of the postprocessing of an I/O request. Additionally, I/O 
postprocessing can queue ASTs to certain processes, thus changing their state 
to computable and resulting in a priority boost. Because all I/O completions 
are accomplished before rescheduling activities, the scheduler can select 
from a potentially larger set of computable processes, using more up-to-date 
information about these processes. 


IPL 8 Through IPL 11 (Fork IPLs) 

On each processor in a VAX system—for each of the IPLs from 8 to 11— 
there exists a queue for fork blocks waiting to be processed. Each fork block 
contains the context of a suspended fork process. The interrupt service 
routine that executes at each of these IPLs (EXESFORKDSPTH) is known as 
the fork dispatcher. The fork dispatcher dequeues a fork block, obtains the 
appropriate fork lock, restores the context of the fork process, and resumes its 
execution at the PC location saved in the fork block (at FKB$L_FPC). (Refer 
to Section 3.3.3 for a discussion of fork blocks and fork processes.) 


All driver routines, except most FDT routines, execute at fork IPL or higher. 
Usually driver routines should not read or alter UCB fields without taking 
steps to ensure synchronization. Because such UCB fields can be shared 
among driver fork processes and VMS system tasks executing on other 
processors in a VMS multiprocessing system, a processor must first secure the 
corresponding fork lock to execute at that fork IPL. Furthermore, the drivers _ 
for all devices on a single I/O adapter must use the same fork lock if they 
actively compete for shared I/O adapter resources such as map registers and 
data paths. The VMS routine that initiates an I/O request on an idle device 
unit, as well as the fork dispatcher, transfers control to the driver with the 
appropriate synchronization. 


A driver places a fork lock index in UCB$B_FLCK using the DPT_STORE 
macro. (See Section 6.1.) VMS determines the appropriate fork IPL from the 
contents of the SPL$B_IPL field in the fork lock’s structure. (See Section 3.2 
for a discussion of spin locks.) 


~ IPL 20 Through IPL 23 (Device IPLs) 


VAX peripheral devices request interrupts at IPLs 20 through 23 because 
device interrupts usually need to preempt most user and VMS software 
functions. When a device requests an interrupt at one of these IPLs and the 
processor is executing at a lower IPL, the processor ‘grants the interrupt, and 
then transfers control to an interrupt service routine for the device located in 
its driver. If the processor is executing at a higher or equal IPL, the interrupt 
remains pending. 


The interrupt dispatcher routes interrupts from. devices to the appropriate 
device driver's interrupt service routine. A driver specifies the address of its 
interrupt service routine in the driver prologue table (DPT). The interrupt 
dispatcher’s routing mechanism works differently depending upon the VAX 
processor and I/O subsystem in use. (For additional information on device 
interrupt dispatching, see the general discussion of interrupt dispatching 

in Chapter 9. Information specific to a given I/O subsystem configuration 
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3.1.2.5 


3.1.3 Additional IPLs 


appears in Sections 12.3 (UNIBUS/Q22 bus), 13.4 (MASSBUS), and 14.3.1 
(VAXBI bus).) 


Data in a device’s registers and in various fields of the UCB that record 
device status is synchronized on the local processor at device IPL, at which its 
driver’s interrupt service routine executes. This value is stored by the driver 
in the UCB$B_DIPL field of the UCB. It is the responsibility of the interrupt 
service routine to secure the corresponding device lock. This action allows it 
to synchronize with other code threads that access the same resources in a 
VMS multiprocessing system. 


The driver’s start-I/O routine is one such code thread and must similarly 
synchronize. In a VMS uniprocessing environment, the routine raises IPL 

to device IPL before writing data in device registers and database fields. In 

a VMS multiprocessor environment, the start-I/O routine must secure the 
appropriate device lock to achieve systemwide synchronization of the device 
database. The act of acquiring the device lock automatically sets IPL to device 
IPL. 


Because code executing at IPLs 20 through 23 blocks most other hardware 
interrupts and all software interrupts on the local processor, driver code 
lowers its IPL as soon as possible. Interrupts from devices on a MicroVAX 
3600-series, MicroVAX II, MicroVAX I, VAX 8200/8250/8300/8350, VAX 
8530/8550/8700/8800 /8830/8850, and VAX 6200-series system, in fact, can 
block hardware interrupts from the processor's interval clock if these device 
interrupts occur at or above IPL 22. To prevent the loss of an interval clock 
interrupt, these drivers, when executing at IPL 22 or above, should lower IPL 
below 22 as soon as possible (within 9 milliseconds). 


IPL 31 (IPL$_POWER) 

The highest IPL, IPL$_POWER (IPL 31) locks out all other interrupts on the 
local processor. Many VMS routines and drivers raise IPL to IPL$_POWER to 
execute code sequences that cannot tolerate interruption. For example, much 
of system initialization occurs at IPL$_POWER. In a VMS multiprocessing 
system, these routines often need to acquire additional synchronization, as 
described in Section 3.2. 


When a device driver needs to execute a series of instructions without 
interruption, the driver raises IPL to IPL6_POWER. The driver should never 
remain at IPL$_POWER for more than a few instructions. The most common 
instance of a driver’s raising IPL to IPL$_POWER is to determine whether 

a power failure has occurred on the local processor between the time that 
the driver writes setup data into device registers and the time that the driver 
starts the device by writing into the device’s control register. 


In addition to the IPLs that are directly involved in the processing of an I/O 
request, VMS defines the IPLs described in this section. 


3.1.3.1 


3.1.3.2 


3.1.3.3 
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IPL 3 (IPL$_RESCHED) 

When an event occurs that requires that a process be rescheduled, a VMS 
routine requests a software interrupt on the local processor at IPL$_ 
RESCHED. The scheduler interrupt service routine (GSCH$RESCHED) gains 
control at this IPL, but immediately obtains the SCHED spin lock (as a result, 
raising IPL to IPL$_SYNCH). This action synchronizes the processor’s access 
to the scheduler’s database with other system activities. 


Drivers never explicitly reference IPL$_RESCHED. Most driver processing 
occurs at higher IPLs. When a process raises IPL to or above IPL$_ 
RESCHED, the scheduler cannot reschedule the process. The process runs 
until an interrupt occurs at a higher IPL or the process lowers IPL below 
IPL$_RESCHED. 


IPL 6 (IPL$_QUEUEAST) 

IPL$_QUEUEAST is a fork-level IPL used predominantly by drivers written 
before Version 4.0 of the VMS operating system. A driver fork process 
originating at an IPL between 8 and 11 would use IPL$_QUEUEAST when it 
needed to synchronize access to the scheduler’s database at IPL$_SYNCH— 
for instance, to queue an AST. Prior to VMS Version 4.0, the only way that 
such a fork process could maintain proper synchronization was to first call 

a system routine that creates yet another fork process to be dispatched at 
IPL$_QUEUEAST. Once the fork dispatcher dequeued the fork block and 
resumed execution of the driver, the driver fork process could then raise IPL 
to IPL$_SYNCH and access the system database. 


Because versions of the VMS operating system after Version 4.0 implement 
IPL$_SYNCH as a fork IPL, a driver fork process can fork directly to IPL$_ 
SYNCH. In VMS Version 5.0, the fork dispatcher obtains the IPL 8 fork 
lock (IOLOCK8), dequeues the driver fork block, restores driver context, 
and resumes execution of the driver. To maintain synchronization in a VMS 
multiprocessing environment, the driver then must obtain the spin lock that 
corresponds to the data structure it is accessing. 


IPL 7 (IPL$_TIMERFORK) 

The interval clock’s interrupt service routine (EXESHWCLKINT), executing at 
IPL 22 or IPL 24 depending upon the VAX system, posts interrupts at IPL$_ 
TIMERFORK. A processor requests such an interrupt when the current process 
has exceeded its processor time quantum. The software timer interrupt service 
routine (EXES$SWTIMINT) gets control when the IPL drops below IPL$_ 
TIMERFORK, services quantum end events by immediately raising IPL to 
IPL$_SYNCH (obtaining the SCHED spin lock, if needed), and calls the 
appropriate scheduler routine. 


The primary processor in a VMS multiprocessor system, when executing 
the interval clock’s interrupt service routine, requests an IPL$_TIMERFORK 
interrupt when the first entry in the timer queue (EXE$GQ_1ST_TIME) 

is due. The software timer interrupt service routine contains special code 
that allows the primary processor to service the expiration of a timer queue 
element (TQE). The routine raises IPL to IPL$_SYNCH, synchronizes access 
to the timer queue (except for the first TQE) by obtaining the TIMER spin 
lock, and secures the interval clock database (the system time at EXE$6GQ_ 
SYSTIME and the expiration time of the first TQE at EXE$GQ_1ST_TIME) 
by obtaining the HWCLK spin lock. Thus synchronized, it determines which 
TQEs have expired, dequeues them, and transfers control to the appropriate 
timeout handlers. Device timeouts are dispatched in this manner. 


Synchronization of I/O Request Processing 
3.1 Interrupt Priority Levels 


3.1.3.4 IPL 8 (IPL$_SYNCH) 
IPL$_SYNCH is the level at which the databases that record and control 
system functions are synchronized. Individual spin locks, such as the JIB, 
SCHED, MMG, and TIMER spin locks, provide synchronized access to 
individual databases in a VMS multiprocessing environment.? When a 
VMS subroutine or a driver needs to modify or read a dynamic portion of a 
system database, the routine always executes at IPL$_SYNCH, holding an 
appropriate system spin lock, to ensure that the database does not change 
because of some interrupt service routine or process action. 


3.1.3.5 IPL 11 (IPL$_MAILBOX) 
IPL$_MAILBOxX is the highest fork IPL. When a VMS or driver routine writes 
into a mailbox, the executing processor must be at IPL$_MAILBOX holding 
the MAILBOX spin lock. Because other readers or writers to the mailbox must 
similarly pursue synchronization, these actions prevent other writers from 
modifying incomplete data in the mailbox and readers from reading invalid 
data. 


3.1.3.6 IPL 14 (XDELTA Entry IPL) 
For debugging purposes, you can halt a processor from the console terminal 
and request a software interrupt to invoke the XDELTA debugger. You 
accomplish this by depositing 0E;¢ in the processor’s Software Interrupt 
Request Register (PR$_SIRR). (The procedure for requesting a software 
interrupt to invoke XDELTA is described in Table 16-3.) 


After you issue the console’s CONTINUE command and return to program 
mode, the processor grants an interrupt. at IPL 14. The processor must be 
executing below the requested IPL for the interrupt to take effect. 


3.1.3.7 IPL 22 or IPL 24 (Interval Clock IPLs) 
Every ten milliseconds, the interval clock interrupts at IPL 22 or 24, 
depending upon the VAX system. A system cell points to the IPL field 
(SPL$B_IPL) in the HWCLK spin lock, identifying the IPL at which the 
processor’s interval clock interrupts. 


The interval clock’s interrupt service routine performs the functions described 
in Section 3.1.3.3. Note that the interval clock’s interrupt service routine 
obtains the HWCLK spin lock to synchronize its operations on the system 
time quadword (EXE$GQ_SYSTIME) and the quadword containing the due 
time of the first timer queue element (EXE$GQ_1ST_TIME). 


3.1.4 Modifying IPL in Driver Code 


Kernel-mode code can modify the IPL of the local processor by either 
explicitly setting the processor’s IPL to a specific value or by requesting a 
software interrupt at a specific level. Driver code can change the IPL at 
which it executes by invoking a VMS-supplied macro to request a change in 
IPL. Because the DEVICELOCK, FORKLOCK, and LOCK macros (and their 
counterparts) only raise (or lower) IPL in a VMS uniprocessing environment, 
but achieve full synchronization in a VMS multiprocessing system, DIGITAL 
recommends their use instead of the SETIPL, DSBINT, and ENBINT macros. 


> IPL$_TIMER, IPL$_SCHED, IPL$_JIB, IPL$_MMG, IPL$_FILSYS, and IPL$_IOLOCKS are all synonyms for 
IPL$_SYNCH (see Table 3-3). 
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Table 3-2 lists the macros that set, store, or restore a processor’s IPL. See 
Appendix B for a further explanation of the functions of these macros and a 
full description of their arguments. 


Table 3—2 VMS Macros That Change a Processor’s IPL 


Macro 
Raising IPL 


DEVICELOCK flockaddr] 
[,lockipl] [,savipl] [,condition] 
[_preserve=YES] 


DSBINT [ip-31] [,dst--(SP)] 
[,environ=MUL TIPROCESSOR 


FORKLOCK flock] [,lockipl] [, savipl] 
[Lpreserve=YES] [,fipNO] 


LOCK lockname [,lockipl] [,savipl] 
[,condition] [,preserve=YES] 


SETIPL [ip-31] 
[,environ=MUL TIPROCESSOR] 


Lowering IPL 


DEVICEUNLOCK [lockadadr] 
[,newipl] [,condition] 
[_preserve=YES] 


ENBINT [src=(SP+)] 


FORKUNLOCK [lock] [,newipl] 
[,condition] [,preserve=YES] 


UNLOCK lockname [,newipl] 
[,condition] [,preserve-YES] 


Miscellaneous Functions 


SAVIPL [dst=—(SP)] 
SOFTINT jp/ 


Function 


Raises IPL on the local processor to the device IPL associated with the 
device lock’s lockaddr, obtains the device lock, and saves the current 
IPL at savipl' 


Raises IPL on the local processor to the specified ip/, saving the 
current IPL at dst 


Raises IPL on the local processor to /ockip!l, obtains the fork lock, and 
saves the current IPL at savipl' 


Raises IPL on the local processor to the /ockip/, obtains the lock 
indicated by lockname, and saves the current IPL at savip!' 


Raises IPL on the local processor to the specified ipF 


Releases or restores the device lock indicated by lockaddr, lowering 
the local processor's IPL to newipl/, thus permitting interrupts to occur 
at or beneath the current IPL’ 


Lowers the local processor's IPL to src, thus permitting interrupts to 
occur at or beneath the current IPL? 


Releases or restores the fork lock indicated by lock, lowering the local 
processor's IPL to newipl/, thus permitting interrupts to occur at or 
beneath the current IPL' 


Releases or restores the spin lock indicated by lockname and lowers 
IPL to newipl, thus permitting interrupts to occur at or beneath the 
current IPL' 


Saves the local processor's IPL at the specified location 


Requests a software interrupt on the local processor at the specified 
ipl 


‘When used in a uniprocessing environment, the DEVICELOCK, DEVICEUNLOCK, FORKLOCK, FORKUNLOCK, LOCK, and 
UNLOCK macros generate only the code that manipulates IPL. 


2Use of the SETIPL, ENBINT, and DSBINT macros is not sufficient to guarantee systemwide synchronization of events 
and data in a VMS multiprocessing system. The DEVICELOCK, FORKLOCK, and LOCK macros have been designed to 
achieve appropriate synchronization in either a uniprocessing or multiprocessing environment. 


Synchronization of 1/O Request Processing 
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Raising IPL 

To block certain activities on a local processor in a VAX system, it is 
sometimes useful to raise IPL explicitly. Driver code should not raise IPL 
for more than a few instructions, for doing so prevents the local processor 
from servicing interrupts at the current IPL and all lower IPLs. 


In a uniprocessor environment, raising IPL provides sufficient systemwide 
synchronization to both block events and also protect data customarily 
accessed at a given IPL. Drivers typically raise a processor’s IPL to check for 
a local processor power failure, send a message to a mailbox, or access device 
registers. For instance, a driver running exclusively in a VMS uniprocessor 
environment can set IPL to its device IPL (UCB$B_DIPL) to access device 
registers. While the driver executes at device IPL, no other code thread can 
execute at the same device IPL and thereby read or write the same device 
registers. (See the discussion in Section 3.1.4.2 for a description of the rules 
for lowering IPL that enforce the synchronization.) VMS supplies the SETIPL 
and DSBINT macros to effect the change in IPL. 


In a multiprocessing environment, as in a uniprocessing environment, a driver 
can block activities on the local processor by raising IPL. However, in a 
multiprocessing environment, simply raising IPL is not sufficient to protect 
shared data structures from other processors that may attempt to access them 
concurrently. To achieve synchronization in a VMS multiprocessing system, 
VMS associates a series of semaphores, called spin locks, with such shared 
databases. (See Section 3.2 for a further discussion of spin locks.) _ 


A processor that must access a shared structure must first secure a 
corresponding spin lock. The acquisition of a spin lock often involves the 
raising of IPL to the IPL associated with the spin lock and the database it 
protects. Spin lock acquisition code can elevate IPL automatically if called 
from a code thread executing at an IPL lower than the synchronization IPL of 
the lock. A processor that has properly obtained a spin lock can thus proceed 
to access the associated database at the appropriate IPL. If necessary, it is free 
to further raise IPL, but should not lower IPL below the spin lock’s allocation 
IPL without first releasing the spin lock. 


For example, a driver running in a VMS multiprocessing system can set 
IPL to IPL$_POWER to block the servicing of a power failure on the local 
processor. However, while executing at IPL$_POWER (or at device IPL), 
the driver cannot safely access device registers unless it has first secured the 
spin lock associated with the device: that is, its device lock. Similarly, a 
driver's fork process, although it executes at a fork IPL with a corresponding 
fork lock held, may raise a processor’s IPL by obtaining an additional spin 
lock. Sending a message to the OPCOM mailbox (obtaining the MAILBOX 
spin lock at IPL 11) and accessing device registers (obtaining the appropriate 
device lock at device IPL) are two such activities. 


The LOCK, FORKLOCK, and DEVICELOCK macros ensure that the 
synchronization needed for either the uniprocessor or multiprocessor 
environment is obtained before the requested resource is accessed. When 
executed in a uniprocessor environment, these macros only obtain the proper 
IPL synchronization. When invoked in a multiprocessing environment, these 
macros both raise IPL and obtain an appropriate spin lock, thus extending IPL 
synchronization systemwide. 


3.2 


3.1.4.2 


Spin Locks 


Synchronization of 1/O Request Processing 
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Lowering IPL 

Driver code lowers its IPL to synchronize with code threads that access 
common data or perform common activities at the lower IPL. In a 
multiprocessing environment, lowering IPL is often associated with the 
release of a spin lock. In addition, lowering IPL may be necessary in order to 
obtain a spin lock synchronized at the lower IPL. 


One of the most fundamental coding rules in VMS is that a code thread cannot 
explicitly lower IPL below the level at which its execution has been initiated. 

In relation to driver processing, this means that a driver fork process cannot 
explicitly set IPL to be less than its fork IPL, nor can a driver’s interrupt 
service routine explicitly set IPL to be less than device IPL. This is because 
a processor interrupted a lower IPL code thread in mid-execution to place 
the current code thread into execution. It is important to the integrity of the 
data structures protected at this lower IPL that the previous code thread be 
resumed before other code accesses the same structures. A violation of the 
IPL rule would undermine the VMS interrupt dispatching mechanism by not 
first returning control to the interrupted code thread. 


Driver code uses the following methods to lower IPL: 


e Issuing a DEVICEUNLOCK, FORKUNLOCK, or UNLOCK macro (paired 
with an earlier invocation of a DEVICELOCK, FORKLOCK, or LOCK 
macro) or a ENBINT macro (paired with an earlier invocation of an 
DSBINT macro) to restore IPL to a previously saved value. 


¢ Invoking the IOFORK (or FORK) macro to preserve its context in a fork 
block, insert the block in a fork queue, and request a software interrupt 
at the driver’s fork IPL. See Section 3.3.3.1 for a complete discussion of 
forking. 


e Issuing an REI instruction at the end of its interrupt service routine that 
dismisses the interrupt. 


Lowering IPL can cause many pending interrupts on the local processor 
between the old and new IPLs to become deliverable. 





In a multiprocessing environment, as in a uniprocessing environment, you 
can block activities on the local processor by raising IPL. Similarly, certain 
shared databases must be accessed only at a given IPL. However, in a 
multiprocessing environment, simply raising IPL on the local processor does 
not prevent other processors in the system from reading or modifying a 
shared database. Unless other steps are taken to notify the other processors 
that the database is “owned,” such contention could potentially result in 
corrupted data and system failures. 


A spin lock is a semaphore associated with a set of system structures, fields, or 
registers whose integrity is critical to the performance of a specific operating 
system task. The scheduler and the memory management subsystem thus 
have their own spin locks, as does each fork processing level and each device 
controller. Because a spin lock can be owned by only one processor in the 
system at a time, other processors attempting to acquire the same spin lock 
are prevented from reading from or writing into the database it protects. 

The structure of a spin lock is pictured in Figure A-15 and described in 
Table A-14. 
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Table 3—3 


Lock Name 


QUEUEAST 


FILSYS 
IOLOCK8 


PR_LK8 | 
TIMER 


JIB 


MMG 


SCHED 


lIOLOCKS 


PR_LK9 


There are two categories of spin lock: 


The structure of a static spin lock is permanently assembled into the 
system. As a result, its existence and definition are fixed from one 
system to another. Static spin locks are accessed as indexes into a vector 
of longword addresses called the spin lock vector and pointed to by 
SMP$AR_SPNLKVEC. The system spin locks and fork locks listed in 
Table 3-3 are static spin locks. 


A dynamic spin lock is a spin lock that is created based on the I/O 
configuration of a particular system. One such dynamic spin lock is 

the device lock SYSGEN creates when configuring a particular device. 
This device lock synchronizes access to the device’s registers and certain 
UCB fields. VMS creates a dynamic spin lock by allocating space from 
nonpaged pool, rather than assembling the lock into the system as it does 
in the creation of a static spin lock. Section 3.2.2 describes device locks. 


Table 3-3 lists, in order of increasing logical rank, the static spin locks. For 
each system spin lock or fork lock, the table records its index into the spin 
lock vector, its synchronization IPL, and a brief description of its function. 


Lock Index 


SPL$C_QUEUEAST 


SPL$C_FILSYS 
SPL$C_IOLOCK8 


SPL$C_PR_LK8 
SPLSC_TIMER 


SPL$C_JIB 


SPL$C_MMG 


SPL$C_SCHED 


SPL$C_IOLOCK9 


SPL$C_PR_LK9 


Static Spin Locks 


Synchronization IPL Description 


6 (IPL$_QUEUEAST) Fork lock for executing a fork process 


at IPL 6 


8 (IPL$_FILSYS)' Lock on file system structures 


8 (IPL$_IOLOCK8)' Fork lock for executing a fork process 


at IPL 8 


8 (IPL$_IOLOCK8)' Primary CPU's private lock for IPL 8 


8 (IPL$_TIMER)' Lock for adding and deleting timer 
queue entries and searching the timer 


queue? 


8 (IPL$_JIB) ' Lock for manipulating job nonpaged 
pool quotas as reflected by the fields 
JIB$L_BYTCNT and JIB$L_BYTLM in 


the job information block 


8 (IPL$_MMG)' Lock on VMS memory management, 
PFN database, swapper, modified 
page writer, and creation of per-CPU 


database structures 


8 (IPL$_SCHED)' Lock on process control blocks, 
scheduler database, and mutex 


acquisition and release structures 


9 (IPL$_IOLOCK9Q) Fork lock for executing a fork process 


at IPL 9 


9 (IPL$_IOLOCK9Q) Primary CPU's private lock for IPL 9 


'IPLS_TIMER, IPL$_SCHED, IPL$_JIB, IPL$_MMG, IPL$_FILSYS, and IPL$_IOLOCK8 are all synonyms for IPL$_SYNCH. 


2The HWCLK spin lock implicitly locks the timer queue element at the head of the timer queue by locking the quadword 
representing its due time (EXE$GO __1ST_TIME). 
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Table 3—3 (Cont.) Static Spin Locks 


Lock Name 
IOLOCK 10 


PR_LK10 
IOLOCK11 


PR_LK11 
MAILBOX 


POOL 
PERFMON 
INVALIDATE 


VIRTCONS 


HWCLK 


MEGA 


MCHECK 


EMB 


Lock Index 
SPL$C_IOLOCK10 


SPL$C_PR_LK 10 
SPL$C_IOLOCK1 1 


SPL$C_PR_LK 11 
SPL$C_MAILBOX 


SPL$C_POOL 
SPL$C_PERFMON 
SPL$C_INVALIDATE 


SPL$C_VIRTCONS 


SPL$C_HWCLK 


SPL$C_MEGA 
SPL$C_MCHECK 


SPL$C_EMB 


Synchronization IPL 
10 (IPL$_IOLOCK10) 


10 (IPL$_IOLOCK10) 


11 (IPL$_IOLOCK1 1) 


11 (IPL$_IOLOCK1 1) 
11 (IPLS_MAILBOX) 


11 (IPL6_POOL) 
15 (IPL$6_PERFMON) 


19 (IPL$_INVALIDATE) 


20 (IPL6_VIRTCONS) 


22 or 24 


31 (IPL$_MEGA) 
31 (IPL$_MCHECK) 


31 (IPL$_EMB) 


3.2 Spin Locks 


Description 


Fork lock for executing a fork process 
at IPL 10 


Primary CPU's private lock for IPL 10 


Fork lock for executing a fork process 
at IPL 11 


Primary CPU's private lock for IPL 11 


Lock for sending messages to 
mailboxes 


Lock on nonpaged pool database 
Lock for |/O performance monitoring 
Lock system space translation buffer 
(TB) invalidation 

Lock for ownership of the virtual 
console 


Lock on interval clock database, 
including the quadword containing 
the due time of the first timer queue 
element and the quadword containing 
the system time 


Lock for serializing access to fork and 
wait queue . 


Lock for synchronizing certain machine 
error handling 


Lock for allocating and releasing error 
logging buffers 


Drivers rarely need to obtain system spin locks or fork locks explicitly; the 
VMS routines that initiate driver processing and access resources protected by 
a spin lock generally obtain and release these locks as required. However, a 
driver must obtain the appropriate device locks whenever it must access data 
synchronized at device IPL; for instance, in its interrupt service routine. 


VMS provides a set of macros, listed in Table 3-2 and described in full 
in Appendix B, that call the system’s spin lock acquisition and releasing 


routines. 


Three factors control the successful acquisition of a spin lock: IPL, rank, and 


ownership. 


IPL 


The processor must be executing at an IPL equal to or below the spin lock’s 
synchronization IPL (SPL$B_IPL). In keeping with the rules discussed 

in Section 3.1.4.2, a processor should not lower the IPL of its thread of 
execution in the process of acquiring a spin lock. Thus, in acquiring a spin 
lock, a processor may or may not raise its IPL, depending upon whether it 
is executing already at the spin lock synchronization IPL. VMS supplies spin 
lock acquisition macros (DEVICELOCK, FORKLOCK, and LOCK) that, in 
calling appropriate VMS routines, raise IPL automatically in the course of 
obtaining the requested spin lock. Once it owns the spin lock, the processor 
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Fork Locks 


can raise its IPL above the IPL at which the spin lock was acquired, but it 
should not lower it below that level. 


Rank 


A processor can own multiple spin locks simultaneously, but must obtain 
these spin locks in increasing order of rank. (Table 3-3 lists the spin locks 
in order of rank.) In other words, a processor that owns one or more spin 


locks should not attempt to acquire a spin lock whose logical rank? is less 
than a spin lock it already holds. It does not need to acquire all spin locks 
of intervening rank. This rule is meant to avoid potential deadlocks in the 
acquisition of system spin locks and fork locks, and does not pertain to device 
locks. The processor may release spin locks in any order, as long as any 
attempt to reacquire those spin locks acquires them in ascending order. 


Note that the concept of rank is independent of IPL. At any given 
synchronization IPL, there may be many spin locks, each of which is ranked 
according to its position in Table 3-3. 


Ownership 


The spin lock must not be owned by any other processor. If the spin lock is 
currently owned by another processor, a requesting processor spin waits for 
the lock to become available. That is, it executes in a loop, waiting for the 
processor that owns the spin lock to release it. If a spin lock is owned, its 
owner field (SPL$6L_OWN_CPU) contains an identifier that indicates which 
processor in the multiprocessor system owns the spin lock. 


It is legal for a processor to nest acquisitions of a given spin lock. In other 
words, if a processor attempts to acquire a spin lock that it currently owns, 
the acquisition will succeed. VMS provides a mechanism whereby such a 
processor can release a single acquisition or all acquisitions of a spin lock. 


In its simplest form, a fork lock is a static spin lock that synchronizes the 
right of a fork process to execute at a specified IPL in a VMS multiprocessing 
system. Fork locks exist for each of the fork IPLs from IPL 8 to 11. A driver 
indicates the fork lock under which it processes, and by implication its fork 
IPL, by specifying a fork lock index in its driver prologue table (using the 
DPT_STORE macro as described in Section 6.1). 


Those code threads that must synchronize with another fork thread use the 
same fork lock. For instance, the fork processes of drivers whose devices 
share the resources of a common adapter must synchronize themselves by 
means of a common fork lock. These code threads fork not necessarily to 
lower IPL, but rather to wait for the availability of a common resource such 
as a controller data channel or map registers (see Section 3.4). The VMS 
routines that acquire and release these resources ensure that the fork lock is 
acquired and released as necessary. 


* The physical rank of a spin lock is the inverse of its logical rank. See the description of the SPL$B_RANK 


field in Table A-14 for additional information. 
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Drivers rarely need to obtain a fork lock explicitly. VMS places the driver 
fork process into execution (originally by EXE$INSIOQ and, by implication, 
by IOC$REQCOM) at fork IPL holding the appropriate fork lock. In addition, 
the fork dispatcher obtains the fork lock associated with the driver fork 
process before it restores its context and resumes its execution. (Section 3.3.3 
describes these concepts in greater detail.) 


Note that, if a driver fork process is not placed into execution by one of these 
means, it must itself expressly obtain the fork lock. 


As an example, consider a driver fork process activated by a timer wakeup 
associated with a timer queue element (TQE) previously queued by the 
driver. The software timer interrupt service routine does raise IPL to IPL 8 
(IPL$_SYNCH) and obtain certain spin locks prior to dequeuing the TQE and 
placing it into execution, but it does not obtain the driver’s fork lock. Thus, 
even though the driver’s fork IPL may be IPL$_SYNCH, the driver will not 
be properly synchronized at fork level unless it first obtains the appropriate 
fork lock. 


A device lock represents a lock on an individual adapter or controller. A 
processor executing a code thread that accesses a device’s registers or certain 
fields in its unit control block (UCB) that reflect its status does so while 
holding the corresponding device lock. 


UCBs are protected by a device lock common to all units on the same adapter 
or common to the entire system, depending upon the type of device. A device 
lock is dynamically created by the System Generation Utility (GYSGEN) when 
it creates a channel request block (CRB). SYSGEN stores the address of the 
device lock in the CRB (CRB$L_—DLCK) and later copies it to the unit control 
block (UCB$L_DLCK) as a UCB is created for each unit on the controller. 


The acquisition of device locks is exempt from the spin lock rank rule. As 
long as the processor does not violate IPL synchronization, it may successfully 
obtain an unowned device lock while holding any system spin lock and, 
likewise, may successfully obtain unowned system spin locks while holding a 
device lock. However, a processor can acquire only one device lock at a given 
IPL. 





3.3 Device Driver Synchronization 


This section describes how VMS and driver processing maintain 
synchronization during the processing of a general I/O request. It later 
focuses on the specific strategies drivers employ to synchronize at the device 
and fork levels. 


3.3.1 


Synchronization of 1/O Request Processing 
3.3 Device Driver Synchronization 
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Overview of the Synchronization of an I/O Operation 


Figure 3-1 diagrams the general flow of the processing of a single I/O 
request, as synchronization is achieved by raising and lowering IPL, and, in 
a multiprocessing environment, by also obtaining and releasing the necessary 
spin locks. 


Figure 3-1 Synchronizing 1/O Request Processing 
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Figure 3-1 illustrates the following events: 
@ The user program, executing at IPL 0, issues a $QIO system service call. 


@ The $QIO system service raises IPL to IPL$_ASTDEL to prepare the I/O 
request according to the arguments included in the call. 


© The driver’s FDT routines execute, mainly at IPL$_ASTDEL. 


Synchronization of |/O Request Processing 


© 


3.3 Device Driver Synchronization 


Note that during IPL 0 processing and FDT routine activity at IPL$_ 
ASTDEL, the process requesting the I/O is susceptible to being 
rescheduled. In a multiprocessing environment, such an event could 
cause I/O processing to resume on a different processor from that on 
which it was started. 


In certain rare circumstances, an FDT routine must read or modify the 
device’s UCB. Because most fields in the UCB may be shared by fork 
processes running systemwide it is important that, if the FDT routine 
must use them, it issue the FORKLOCK macro to obtain the appropriate 
fork lock and raise to fork IPL. (When finished, it relinquishes this 
synchronization by issuing the FORKUNLOCK macro.) 


The continuation of VMS preprocessing of the I/O request—or the 
completion of a previous I/O request on the device unit—ensures that 
the driver’s start-I/O routine is placed into execution at fork IPL and, 
in a multiprocessing system, holding the corresponding fork lock. The 
start-I/O routine accesses various UCB fields and contends for adapter 
resources synchronized systemwide by the fork lock. 


Once it has further prepared the I/O request and obtained the required 

resources, it generally must access device registers. Device registers and 
those UCB fields that record their status are synchronized at device IPL. 
A processor in a VMS multiprocessing system must hold the appropriate 
device lock to access the device database. 


While executing a critical code sequence, such as those instructions that 
start a device, the start-I/O routine raises the IPL of the local processor 
to IPL$_POWER to check for a processor power failure. In a VMS 
multiprocessing environment, the executing processor retains the device 
lock during this sequence. 


After it activates the device, the start-I/O routine calls a VMS routine 
that saves the driver’s context in the UCB fork block, suspends driver 
processing, releases the device lock, if held, and restores IPL to a previous 
level. 


VMS at this point returns control to the code that initiated the fork thread 
where, in a VMS multiprocessing system, the fork lock is released. 


After VMS services interrupts at intervening IPLs, the user process 
resumes. 


Figure 3-2 illustrates the synchronization involved in the completion of an 
I/O request from the point of the device interrupt to the delivery of ASTs 
to the user program. There is little linear flow involved in the completion 
of an I/O request. The servicing of interrupts, represented by jagged lines 
in the figure, the requesting of software interrupts, and the REI instruction 
contribute to the flow that completes an I/O request. 
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Figure 3—2 Synchronizing |/O Request Completion 
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Figure 3-2 illustrates the following events: 


@ A device interrupt in the range of IPL 20 through IPL 23 triggers the 
execution of the driver’s interrupt service routine. The interrupt service 
routine locates the device unit’s UCB and, in a VMS multiprocessing 
system, immediately obtains the appropriate device lock. After it analyzes 
the interrupt and determines that it is expected, it reactivates the driver, 
still at device IPL and holding any acquired device lock. 


@ The driver briefly examines and/or saves the contents of the device's 
registers, but, in order to permit other device interrupts to be serviced 
and to allow other high priority system tasks to proceed, it lowers its 
own priority. The driver accomplishes this by requesting VMS to save 
some driver context in the UCB fork block and place it into one of the 
processor-specific fork queues at IPLs 8 through 11 serviced by the fork 
dispatcher. When it does so, VMS returns control to the driver’s interrupt 
service routine. 
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© The interrupt service routine releases any acquired device lock and issues 
an REI instruction to dismiss the device interrupt. 


@ When IPL drops below the driver’s fork IPL, the fork dispatcher 
restores the context of the driver and resumes its execution. In a VMS 
multiprocessing system, the fork dispatcher obtains the necessary fork 
lock prior to placing the driver into execution. 


© Still synchronized at fork level, the driver fork process analyzes the 
success of the I/O operation and writes status into RO and R1. VMS 
then inserts the IRP into the local processor’s I/O postprocessing queue, 
requests a software interrupt at IPL6$_IOPOST, and starts any I/O request 
that may be waiting for the device. Eventually, VMS returns to the fork 
dispatcher and, if no other fork processes are queued for that IPL, issues 
an REI instruction to dismiss the software interrupt. 


@ When the processor’s IPL falls below IPL$_IOPOST, the I/O 
postprocessing routine removes the IRP from the I/O postprocessing 
queue, adjusts process quota usage, and deallocates system buffers for 
write functions. 


@ When the routine finishes processing the IRP, it queues a special kernel- 
mode AST to the process that issued the original $QIO request. To 
accomplish this, it obtains the SCHED spin lock (raising to IPL$_SYNCH 
in the process) and calls another VMS routine that queues the AST to the 
process’s PCB. It then releases the SCHED spin lock. 


© The I/O postprocessing routine continues execution at IPL$_IOPOST 
until it has serviced all entries in the postprocessing queue. It then issues 
an REI to dismiss this software interrupt. 


© The special kernel-mode AST routine executes at IPL$_ASTDEL. It 
~ completes the transfer of the results and status of the I/O request to the 
user process. 


@ The special kernel-mode AST routine can queue a user-mode AST routine 
to the user process. When the user process has been rescheduled and its 
context reloaded, the user-mode AST routine executes at IPL 0. 


3.3.2 Synchronizing the Device Database 


A device database ordinarily consists of the device or adapter registers, plus 
some storage in the UCB (or in another data structure) that reflects the status 
of the device. Routines that access data in the device database must do so at 
device IPL (UCB$B_DIPL) in order to maintain synchronization. Generally, 
only three driver routines contend for access to the device database. 


e Interrupt service routine 
e  Start-I/O routine when loading or reading device registers 


¢ Timeout handling routine 


In a VMS uniprocessing environment, the start-I/O routine raises its IPL to 
device IPL using the DSBINT macro. VMS calls the driver’s timeout handling 
routine at device IPL. Because the interrupt dispatcher invokes it at device 
IPL, the driver’s interrupt service routine does not need to acquire additional 
synchronization. 
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In a VMS multiprocessing environment, these routines must also hold the 
appropriate device lock (UCB$L_DLCK). The device lock protecting the 
device database is a dynamic spin lock, created by SYSGEN when the device 
is configured and its channel request block (CRB) is created. The address of 
the device lock is first stored in CRB$L_DLCK and is moved to UCB$L— 
DLCK as corresponding UCBs are allocated for each unit on the controller. 
VMS calls the driver’s timeout handling routine at device IPL with the device 
lock held. The start-I/O routine and the interrupt service routine must 
explicitly obtain such synchronization by invoking the DEVICELOCK macro. 


The start-I/O routine and timeout handling routine are additionally 
synchronized at driver fork level. VMS raises IPL to fork level and obtains the 
corresponding fork lock before transferring control to them. This is not the 
case, however, with a driver's interrupt service routine. A device’s interrupt 
service routine usually does not hold the fork lock. However, it may have 
preempted a thread holding the fork lock, or a fork thread may be running 
in parallel on another processor. Therefore, an interrupt service routine must 
not change any fields in the UCB that are protected by the fork lock. To 
access these fields, an interrupt service routine must fork, as described in 
Section 3.3.3.1. 


3.3.3 Synchronizing at Driver Fork Level 
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A large part of driver code executes in the context of a fork process. As a 
fork process, driver code that must access data in its fork database does 

so at a single, specific fork IPL (from IPL 8 to IPL 11) and—in a VMS 
multiprocessing environment—holding a single, specific fork lock (see 
Section 3.2.1). The fork database consists of those fields in the unit control 
block (UCB) not explicitly synchronized at device level and such adapter or 
controller resources as map registers or data paths. 


The system routine EXE$INSIOQ initially creates a driver fork process as 

it attempts to deliver a preprocessed I/O request to the driver’s start-I/O 
routine. If the device unit is busy (that is, a fork process is already active 
servicing a prior request for that device), EXE$INSIOQ inserts the IRP into 
the UCB’s pending-I/O queue. If the device unit is not busy, EXE$INSIOQ 
calls IOC$INITIATE to transfer control to the driver's start-I/O routine. The 
start-I/O routine begins to execute at fork IPL holding the associated fork 
lock, if necessary. 


When the driver fork process later calls IOC6REQCOM to complete 
processing of a prior I/O request, IOC$REQCOM executes within the driver 
fork process, dequeues the next IRP on the pending-I/O queue, and begins 
processing it. 


Like other processes, fork processes can be interrupted or suspended. The 
local processor interrupts a fork process when the processor receives a 
request for an interrupt at a higher priority level. To minimize the number of 
interruptions, fork processes sometimes execute at raised IPLs, and even raise 
their IPL to block all other interrupts, if necessary. 


VMS stalls a driver’s fork process when the process requests an unavailable 
resource such as a controller’s data path (see Section 3.4). When suspended, a 
driver fork process, like other processes, preserves some context information. 
As VMS preserves some of the context of a normal process in its hardware 
PCB, so it preserves a driver fork process’s context—however abbreviated—in 
a fork block. Fork context consists of the following: 
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e Two general purpose registers (R3 and R4) 
e The program counter (PC) 


e A fork block (usually the UCB), the address of which is in R5 at the time 
of the suspension 


Minimal context helps ensure that, when a driver fork process is ready to be 
resumed, the resulting context-switching occurs swiftly. 


Forking and the VMS Fork Dispatcher 
Forking allows high IPL code to do the following: 


¢ Continue executing a particular code thread at a lower IPL than the IPL 
at which the code thread was initiated 


: Synchronize with other code executing at the lower IPL 


Usually, a driver forks after servicing a device interrupt at an IPL from 20 
through 23. By forking, the driver lowers the IPL at which it continues 

to process the device interrupt from device IPL to fork IPL (8 through 

11). Forking not only allows the driver to process efficiently that part of 
interrupt request processing that is not time critical, but it allows the driver 
to synchronize its execution with other fork process code threads initiating 
I/O. For example, forking helps the driver synchronize its use of a device 
unit’s UCB with other code threads interested in the structure. Moreover, the 
driver, by forking after completing the initial servicing of a device interrupt, 
allows other device interrupts to occur at that device IPL. 


To fork, either the driver’s interrupt service routine or the start-I/O routine, 
when resumed by the interrupt service routine, invokes the VMS macro 
IOFORK. The IOFORK macro saves fork process context in the UCB fork 
block, places the fork block in the local processor’s fork queue for the specific 
fork IPL, and requests a software interrupt for that IPL. When that interrupt 
is ultimately serviced, driver fork processing resumes at the lower level. 


There are other specialized instances in which a device driver may fork. 

As discussed in Section 11.1.5, the driver’s unit initialization routine or 
controller initialization routine, while executing at IPL 31, may fork in order 
to permanently allocate controller resources, system nonpaged dynamic 
memory, or system page-table entries. To fork, these routines use the VMS 
macro FORK. The FORK macro allows a driver to fork, utilizing the fork 
block, the address of which is placed in R5. Because the channel request 
block (CRB) is available to these routines and contains a fork block, they 
invoke the VMS macro FORK with the address of the CRB in R5. 


One interrupt service routine (EXE$FORKDSPTH) handles all fork-process 
dispatching on each processor in a VAX system. When the processor grants 
an interrupt at fork IPL, the fork dispatcher saves RO through R5 on the 
stack and processes the local fork queue that corresponds to the IPL of the 
interrupt. To do so, it removes an entry from the fork queue, restores the 
fork process context from the fork block, obtains ownership of the fork lock 
specified in the fork block (in a VMS multiprocessing system), and reactivates 
the suspended fork process. 


When that fork process is completed, the dispatcher releases the fork lock and 
examines the fork queue. If an entry exists on the queue, the fork dispatcher 
removes it, restores the context of the fork process, secures the fork lock 
specified in the fork block, and reactivates the fork process. This sequence is 
repeated until the fork queue is empty. When the queue is empty, the fork 
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dispatcher restores RO through R5 from the stack and dismisses the interrupt 
with an REI instruction. 


Figure 3-3 illustrates the fork queue structure. 


Figure 3-3 Processor-Specific Fork Queue Structure 
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3.3.3.2 Restrictions on Fork Processes 
A driver fork process executes under the following constraints: 


e It should not attempt to refer to the address space of the process initiating 
the I/O request. 


e It can use only RO through R5 freely; it must save other registers before 
use and restore them after use. Use of registers other than RO through R5 
is strongly discouraged. 


e It must clean up the stack after use; the stack must be in its original state 
when the fork process relinquishes control to any VMS routine. 


e It must execute at IPLs between the driver’s fork IPL and IPL$_POWER. 
It must not lower IPL below the driver’s fork IPL except by creating a 
fork process to execute at a lower IPL. 


e If executing in a VMS multiprocessing environment, it cannot attempt to 
obtain system spin locks with lower ranks than that of its fork lock. 


¢ When it returns control to the fork dispatcher, the fork process must be 
at the same fork IPL and, if executing on a VMS multiprocessing system, 
own the appropriate fork lock. 
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3.4 Resource Wait Queues 


The processing of an I/O request often requires shared system resources 
such as memory and I/O adapter map registers. Drivers that depend on 
such resources synchronize access to these resources and their respective 
resource wait queues by executing at fork IPL and, in a VMS multiprocessing 
environment, obtaining ownership of the associated fork lock. 


The $QIO system service and fork processes call VMS routines to allocate and 
deallocate shared system resources. Because the resources are limited, I/O 
processing might be delayed until any such needed resources are released. 
Thus, synchronization of access to these resources can have a substantial 
impact on the processing of I/O requests. 


For example, the $QIO system service calls a VMS routine to allocate 
nonpaged system space for an IRP. If there is insufficient nonpaged pool, 
the routine calls another VMS routine to save the process context and change 
the process state to resource-wait mode (also called miscellaneous wait, or 
MWAIT). As a result of waiting, the process is a candidate to be swapped 
out of memory. When nonpaged pool becomes available, the scheduler 
reschedules the process. 


During fork process execution at elevated IPLs, driver context is very small. 
At any point, the driver can obtain all details about an I/O request by 
referring to the I/O database (see Appendix A). The driver needs only the 
address of the device’s UCB, which is the key to the rest of the database. 
Therefore, VMS routines that control driver resources, such as map registers, 
use fork blocks and resource-wait queues to save minimal driver context. 
Each entry in a queue is a fork block (or UCB) that contains R3, R4, and the 
continuation PC of the waiting fork process. 


When the awaited resource becomes available, the routine controlling the 
resource performs the following steps: 


e Restores the UCB address to R5 

e Restores the saved registers R3 and R4 

e Grants the resource 

e Transfers control to the saved driver return PC address 

Because the VMS routine that controls a particular resource stalls any driver 
that requests an unavailable resource, drivers are unaware of execution being 
suspended and subsequently reactivated. Drivers must not leave anything on 


the stack, or in general purpose registers, other than R3, R4, and R5, when calling 
a routine that might suspend the driver's execution. 


3.4.1 Competing for a Controller’s Data Channel 


A controller’s data channel is a VMS synchronization mechanism that 
guarantees that only one unit of a multiunit controller uses the controller 
at one time. 


Devices that share a controller, such as disk units, own the controller’s data 
channel only when a VMS routine assigns the channel to the unit’s fork 
process. The device driver’s start-I/O routine issues the REQPCHAN macro 
to obtain the channel. . 
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In contrast, a device unit on a single-unit controller always owns the 
controller’s data channel. The device driver’s controller (or unit) initialization 
routine affirms this fact by moving the address of the device’s UCB into 
IDB$L_OWNER. Generally, the driver’s start-I/O routine does not request a 
single-unit controller. 


In each case, the driver’s start-I/O routine must take steps to synchronize its 
access to device registers with any access of these registers by the driver's 
interrupt service routine. The routine does so by issuing the DEVICELOCK 
macro (as described in Section 3.1.4). The DEVICELOCK macro raises IPL 
to device IPL and, in a VMS multiprocessing system, obtains the device lock 
associated with the controller. 


An RK611 controller, for example, controls as many as eight RKO6/RKO07_ 
devices. The disk driver’s fork process must gain control of the controller’s 
data channel before starting an I/O operation on the unit associated with the 
fork process. The disk driver’s start-I/O routine uses the following sequence 
to start a seek operation on an RKO7 device: 


1 The start-I/O routine requests the controller’s data channel by invoking a 
VMS channel arbitration macro (REQPCHAN). 


2 The VMS routine tests the CRB mask field to determine whether the 
controller’s data channel is available. 


3 If the channel is available, the VMS routine allocates the channel to 
the fork process and returns the address of the device’s CSR to the fork 
process. 


If the channel is busy, the VMS routine saves the driver fork context in 
the UCB fork block and inserts the fork block address in the controller’s 
channel wait queue. 


4 When the fork process resumes execution, the process owns the controller 
channel. The fork process can then obtain the device lock (raising IPL to 
device IPL) and modify the device’s registers to activate the device. 


5 The driver’s start-I/O routine then requests the VMS operating system to 
suspend driver processing in anticipation of an interrupt or timeout and 
to release the channel. 


6 The VMS channel-releasing routine assigns channel ownership to the 
next fork process in the channel wait queue, loads the CSR address into a 
general register, and reactivates the suspended fork process. 


7 The reactivated fork process continues execution as though the channel 
had been available in the first place. 


The VMS channel-arbitration routines keep track of controller availability 
using a flag field in the CRB. The fork process must always request and 
release the controller’s data channel by invoking these routines. 


4 Overview of I/O Processing 


Under the VMS operating system, I/O processing occurs in three major 
phases: 


e I/O request preprocessing 
e Device activation and subsequent handling of the device interrupt 


e I/O postprocessing 


When a user process issues an I/O request, the Queue I/O Request ($QIO) 
system service gains control and coordinates preprocessing of the request. 
The last driver FDT routine called by the $QIO system service calls a VMS 
routine that creates a driver fork process to execute the driver’s start-1/O 
routine. This routine activates the device. 


When the transfer is completed, the device requests an interrupt that 
results in execution of the driver’s interrupt service routine. This routine 
handles the interrupt and requests resumption of the driver fork process 
to perform device-dependent I/O postprocessing. The driver fork process 
finally transfers control to the system to perform device-independent I/O 
postprocessing. Figure 4-1 illustrates the sequence of events. 


The $QIO system service is dispatched by means of a corresponding system 
service vector in process P1 space. This vector contains a CHMK instruction 
that causes an exception that alters the process’s access mode to kernel and 
dispatches to the service-specific procedure, EXE$QIO. For the purposes of the 
discussion in this section, as well as the rest of the book, Figure 4-2 portrays 
the flow of an I/O request from its system service entry point to its servicing 
by VMS executive routines and driver code. Discussion of other entry points 
appears in Chapters 8, 9, and 10. 





4.1 Preprocessing an I/O Request 


EXE$QIO performs device-independent preprocessing of an I/O request and 
calls driver FDT routines to perform device-dependent preprocessing. To 
preprocess an I/O request, EXE$QIO takes the following steps: 


e Verifies that the requesting process has assigned a process I/O channel to 
the target device 


e¢ Locates the device driver in the I/O database 

e Validates the I/O function code 

e Checks process I/O request quotas 

e Validates the I/O status block _ 

e Allocates and sets up the I/O request packet (IRP) 


¢ Calls driver FDT routines to perform device-dependent preprocessing 
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Figure 4—1 Sequence of Driver Execution 
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Figure 4-2 Detailed Sequence of VMS I/O Processing 
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Process I/O Channel Assignment 


The first step in preprocessing an I/O request is to verify that the I/O request 
specifies a valid process I/O channel. The process I/O channel is an entry 
in a system-maintained process table that describes a path of reference from 
a process to a peripheral device unit. Before a program requests I/O to a 
device, the program identifies the target device unit by issuing an Assign- 
I/O-Channel ($ASSIGN) system service call. The $ASSIGN system service 
performs the following functions: 


e Locates an unused entry in the table of process I/O channels 
e Creates a pointer to the device unit in the table entry for the channel 


e Returns a channel-index number to the program 
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When the program issues an I/O request, EXE$QIO verifies that the channel 
number specified is associated with a device and locates the unit control block 
associated with the specified channel using the field CCB$L_UCB. 


Refer to Figure A-4 and Table A-3 for an illustration of the channel control 
block and a description of its contents. 


4.1.2 Locating a Device Driver in the 1/O Database 


4.1.2.1 


A unit control block (UCB) that describes a device unit exists for each device 
in the system. The UCB indicates the current state of the device unit by 
recording such information as the following: 


e Whether the device is active (UCB$V_BSY in UCB$L_STS) 
e What I/O request is being processed (UCB$L_IRP) 
e Where transfer buffers are located (UCB$L_SVAPTE) 


Because drivers run as fork processes and cannot use process address space 
to store additional context, drivers use the UCB for temporary data storage 
during I/O processing. (Section 6.1 describes how you can allocate additional 
UCB space for storing data or device-dependent driver context.) 


The UCB also holds the context of a driver fork process when VMS I/O 
routines suspend the fork process to wait for an asynchronous event such as 
a device interrupt. 


Using information in the UCB, a driver can find other I/O data structures 
associated with the device, including the channel request block, interrupt 
dispatch block, and the device data block. 


Figure A-17 represents a UCB and Table A-16 describes its fields. 


Channel Request Block 
The channel request block (CRB) allows the operating system to manage the 
controller data channel. Among its contents are the following: 


¢ Code that transfers control to a driver’s interrupt service routine (CRB$L_ 
INTD) 


e A pointer to the driver’s interrupt service routine (CRB$L_ 
INTD+VEC$L _ISR) 


e Addresses of a driver’s unit and controller initialization routines (CRB$L — 
INTD+VEC$L_UNITINIT, CRB$L_INTD+VEC$L _INITIAL) 


¢ A pointer to the interrupt dispatch block (IDB), which further describes 
the controller (CRB$L_INTD+VEC$L —_IDB) 


Controllers can be either multiunit or dedicated. 


All UCBs describing device units attached to a single multiunit controller 
contain a pointer to a single CRB (UCB$L_—CRB). For these controllers, a 
VMS routine uses fields in the CRB (CRB$L_WQFL, CRB$B_MASK) and 
IDB (IDB$L_OWNER) to arbitrate pending driver requests for the controller. 
When the system grants ownership of a multiunit controller data channel to a 
driver fork process, the fork process can initiate an I/O operation on a device 


4.1.2.2 
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attached to that controller. Figure 4-3 illustrates the data structures required 
to describe three devices on a multiunit controller. 


Figure 4—3 Data Structures for Three Devices on One Controller 
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The VMS operating system does not use the CRB to synchronize I/O 
operations for a dedicated controller, as the controller manages but a single 
device. Nevertheless, the CRB still is present and is used by drivers and 
operating system routines. 


See Figure A-6 and Table A-5 for an illustration of the CRB and a description 
of its contents. 


Interrupt Dispatch Block 

The CRB contains a pointer to an interrupt dispatch block (IDB) (CRB$L— 
INTD+VEC$L-_IDB). In turn, the IDB (at IDB$L_UCBLST) points to all UCBs 
that share the controller (see Figure 4-3). 


The IDB contains the addresses of these three critical data structures: 


e The UCB of the device unit, if any, that currently owns the controller data 
channel (IDB$L_OWNER) 


¢ The control and status register (IDB$L_—CSR); it is the key to access to 
device registers 


e The adapter control block (IDB$L_ADP) that describes the adapter of the 
I/O bus to which the controller is attached 


A detailed description of the fields in the IDB appears in Table A-10; 
Figure A-11 shows its structure. 


Overview of I/O Processing 
4.1 Preprocessing an I/O Request 


4.1.2.3 


Figure 4—4 illustrates the relationship between the data structures that 
describe a group of equivalent devices on two separate controllers. In this 
figure, one controller has a single device unit, and the other controller has 
two device units. Devices on both controllers share the same driver code. 


Figure 4—4 |/O Database for Two Controllers 
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Device Data Block 

All UCBs describing device units attached to a single controller contain 
a pointer (UCB$L_DDB) to a single device data block (DDB). The DDB 
contains two fields that identify the device and its driver: 


e The generic device/controller name (DDB$T_NAME) 


e The name of the device’s driver as obtained from the driver prologue 
table (DDB$T_DRVNAME) 


Table A-7 further describes the fields of the DDB. For a representation of its 
structure, see Figure A-8. 
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4.1.3 Validating the I/O Function 


Using the I/O database, EXE$QIO locates the address of the driver’s function 
decision table by following a chain of pointers that begins in the UCB of the 
target device: 


UCB — DDT — FDT 


EXE$QIO then uses data in the function decision table to analyze the I/O 
function. The procedure confirms that the function specified in the I/O 
request is a valid function for the device. 


4.1.4 Checking Process I/O Request Quotas 


EXE$QIO determines whether the I/O request being readied will cause the 
process to exceed its quota for outstanding direct or buffered I/O requests. 

If the process’s requests remain under quota, the system service allows it 

to continue I/O preprocessing. Where quota is exceeded, the procedure 
examines the process’s resource wait flag (PCB$V_SSRWAIT in PCB$L_STS). 


If the flag is clear, EXE$QIO aborts the I/O request. However, if the flag is 
set, it places the process in a wait state until previously issued I/O requests 
complete and the number of requests drops below quota. When this occurs, 
process execution resumes, at which time EXE$QIO charges process quotas as 
appropriate for the requested operation. 


4.1.5 Validating the I/O Status Block 


If the I/O request specifies a quadword I/O status block to receive final I/O 
status information, EXE$QIO determines whether the process issuing the 
request has write access to the status block locations specified. If the process 
has write access, EXE$QIO fills the quadword with zeros. If the process does 
not have write access, the procedure terminates the request with an error 
status. 


4.1.6 Allocating and Setting Up an I/O Request Packet 


If validation of the I/O request succeeds to this point, EXE$QIO allocates a 
block of nonpaged pool to contain an IRP. 


Before EXE$QIO allocates an IRP, it raises the IPL of the processor to IPL$_ 
ASTDEL to block any other asynchronous activity in the process. The new 
IPL prevents possible deletion of the process; process deletion would result in 
the operating system’s losing track of the pool allocated for the IRP. 


EXE$QIO attempts to allocate an IRP from a lookaside list containing 
preallocated IRPs. If no preallocated packets exist, the procedure calls a VMS 
routine that allocates an IRP from general nonpaged pool. This allocating 
routine synchronizes with the rest of the system so that it can allocate the 
memory needed. 
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EXE$QIO resumes I/O preprocessing by writing a description of the I/O 
request into the fields of the IRP as follows. Note that this data encompasses 
the device-independent information associated with the request. It is up to 
the device driver’s FDT routines or VMS common FDT routines to fill in 

the device-dependent portions of the IRP, as described in Section 4.1.7 and 


Chapter 7. 


Data 


Size in bytes of the IRP 
Identification of the block as an IRP 


Access mode of the process at the time of the 
request 


Process ID of the requesting process 


Address of an AST routine (if specified in the 
request) and its parameter’ 


For file-structured devices, address of a 
window control block (WCB) that describes 
the physical location of part of the file 


Address of the target device’s UCB 
|/O function code? 


Number of event flag to set when processing 
of the I/O request is complete 


Base software priority of the requesting 
process 


Address of an I/O status block (if specified in 
the request) 


Process I/O channel index number 


A flag indicating whether the I/O function is for 
buffered or direct I/O ; 


A flag indicating whether the !/O request is an 
input request 


A flag indicating whether the !/O function is a 
physical-I/O function 


Address of a diagnostic buffer (if specified in 
the request)?and a flag indicating that the buffer 
is present 


Address of process's access rights block 
|/O transaction sequence number 


Field(s) 


IRP$W_SIZE 
IRPSB_TYPE 
IRPSB_RMOD 


IRP$L_PID 
IRP$L_AST, IRP$L_ASTPRM 


IRPSL__WIND 


IRP$L_UCB 


IRP$W_FUNC 
IRP$B_EFN 


IRP$B_PRI 


IRP$L_IOSB 


IRP$ W_CHAN 
IRP$V_BUFIO in IRP$SW_STS 


IRP$V_FUNC in IRP6W_STS 


IRP$V_PHYSIO in IRP$W_STS 


IRP$L_DIAGBUF, IRP$V_ 
DIAGBUF in IRP$W_STS 


IRP$L_ARB 
IRP$L_SEQNUM 


‘lf the request specifies an AST, EXE$QIO also verifies that the request would not cause 
the process to exceed its AST quota. If it would, EXE$SQIO aborts the request. 


2For nonfile devices (DEV$V_FOD clear in UCB$L_DEVCHAR), EXE$QIO reduces read- 
and write-virtual-block functions to their equivalent read- and write-logical-block functions 


before storing a code. 


3The size of the diagnostic buffer is specified in the driver dispatch table of the driver 
servicing the device unit to which the request is made. See Section 6.2 for more 


information. 


4.1.7 


FDT Processing 
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Figure A-12 illustrates the format of an IRP; Table A-11 describes each of its 
fields. 


The driver’s function decision table controls the device-dependent 
preprocessing of an I/O request. Figure 4-5 illustrates the layout of a function 
decision table. 


Figure 4—5 Layout of a Function Decision Table 


2 longwords 


functions 


buffered I/O 


2 longwords 


3 longwords 


3 longwords 





ZK-921-82 


The I/O function code specified in an I/O request is a 16-bit value consisting 
of two fields: 


e A 6-bit I/O function code (bits 0 through 5) that permits you to define 
64 unique I/O function codes for every device type. Table 6-1 lists the 
function codes defined by VMS. Section 6.3.2 describes how you can 
define device-specific function codes. 


e A 10-bit I/O function modifier (bits 6 through 15). In subsequent 
processing of the I/O request, the driver’s start-I/O routine uses both 
I/O function code and I/O function modifier, as stored in IRP$W_FUNC, 
to create a device-specific function code to use in device activation. 


The first two entries of a function decision table are two longwords (64 
bits) each. The first quadword entry is the legal function bit mask of all 1/O 
function codes that are valid for the device. The second quadword entry 
is the buffered function bit mask of those valid I/O functions that are also 
buffered-I/O functions. 
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Note: 


EXE$QIO uses the value of the low-order six bits of the I/O function code to 
determine which bit to check in each of these bit masks. For example, if the 
function code has a value of 22, the procedure checks the twenty-third bit (bit 
22) of each bit mask. Thus, EXE$QIO determines whether the I/O function 
code is valid for the device and is able to charge against the appropriate quota 
of the requesting process for a direct- or buffered-I/O operation.' 


Subsequent entries in the function decision table are three longwords long, 
and it is these entries that EXE$QIO uses to dispatch to the appropriate I/O 
preprocessing routine (FDT routine) for the requested function. Again, the 
first quadword is a 64-bit bit mask, and is checked by EXE$QIO in exactly 
the same way as the legal function bit mask and the buffered function bit 
mask. These action routine bit masks, however, contain the address of an 
FDT routine in the subsequent longword, and it is to this FDT routine that 
EXE$QIO transfers control when it discovers the bit corresponding to the I/O 
function set in the quadword. 


Some FDT routines are present in the operating system because they provide 
common services for many devices. Section 7.5 describes these routines. 
Other routines are included in the device driver because they perform device- 
dependent services. 


EXE$QIO uses the action routine bit mask entries in the function decision 
table to call FDT routines in the driver or system, according to the following 
strategy: 


1 If the bit corresponding to the function code is set in the action routine 
bit mask, EXE$QIO calls the FDT routine whose address appears in the 
following longword. 


e If this I/O function requires additional preprocessing after this 
particular FDT routine completes its activity, the FDT routine returns 
control to EXE$QIO with an RSB instruction. When EXE$QIO regains 
control, it advances to the next action routine bit mask and repeats 
step 1. 


e If this FDT routine completes all necessary preprocessing for this 
particular I/O function, then it transfers control to a VMS routine that 
queues the IRP or completes the request. 


2 If the bit corresponding to the function code is not set, EXE$QIO advances 
to the next action routine bit mask in the table and repeats step 1. 


A single function decision table can specify that EXE$QIO call more 
than one FDT routine to perform the many and varied steps in the 
preprocessing of a single I/O function. However, it is the responsibility 
of the FDT routine that ultimately completes the preprocessing to end 
the scan (by EXE$QIO) of the function decision table. An FDT routine — 
accomplishes this by transferring control to either a VMS routine that 
queues the I/O request for the driver's start-I/O routine or one that 
completes or aborts the request (see Figure 4-2). In other words, for each 
valid I/O function code for a device, an FDT entry must contain the 
address of a routine that ends I/O preprocessing. 


' For physical- and logical-I/O operations, EXE$QIO also verifies that the process making the I/O request has 


suitable privileges. 
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Figure 4—6 FDT Routines and I/O Preprocessing 
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4.2.1 
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FDT routines execute in the context of the process that requested the I/O 
operation. Thus, FDT routines can access process virtual address space. Once 
all FDT preprocessing is complete, however, the rest of the processing for the 
I/O request continues in the limited context of a driver fork process or an 
interrupt service routine. 





Handling Device Activity 


When I/O preprocessing is complete, the last-called FDT routine generally 
jumps (with a JMP instruction) to a routine called EXE$QIODRVPKT.? 
EXE$QIODRVPKT, in turn, transfers control (using a JSB instruction) to 
EXE$INSIOQ, the VMS routine that queues IRPs and arbitrates device 
activity. (See Figure 4~—2 for a representation of the flow of I/O request 
processing at this juncture.) 


Creating a Driver Fork Process to Start I/O 


EXE$INSIOQ creates only one driver fork process at a time for each device 
unit on the system. As a result, only one IRP for each device unit is serviced 
at one time. EXE$INSIOQ determines whether a driver fork process exists for 
the target device, as follows: 


e If the device is idle, no driver fork process exists for the device; in 
this case, EXESINSIOQ immediately calls IOC$INITIATE to create and 
transfer control to a driver fork process to execute the driver’s start-I/O 
routine. 


e If the device is busy, a driver fork process already exists for the device, 
servicing some other I/O request. In this case, EXE$INSIOQ calls 
EXE$INSERTIRP to insert the IRP into a queue of IRPs waiting for 
the device unit. The routine queues the IRP according to the base priority 
of the caller. Within each priority, IRPs are in first-in/first-out order. The 
completion of the current I/O request triggers the servicing of the I/O 
request that is first in the queue, according to the procedure described in 
Section 10.1.2.3. 


In the latter case, by the time the driver’s start-I/O routine gains control to 
dequeue the IRP, the originating user’s process context is no longer available. 
Because the context of the process initiating the 1/O request is not guaranteed 
to a driver's start-I/O routine, the driver must execute in the reduced context 
available to a fork process. 


IOC$INITIATE always initiates the driver’s start-I/O routine with a context 
that is appropriate for a fork process. VMS establishes this context by 
performing the following steps: 


1 Raising IPL to driver fork IPL (and obtaining the associated fork lock in a 
VMS multiprocessing environment) 


2 Loading the address of the IRP into R3 
3 Loading the address of the device’s UCB into R5 


* The rules for exiting from FDT preprocessing, including descriptions of EXESQIODRVPKT and other FDT exit 
routines, appear in Sections 7.2.1 and 7.2. 
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Transferring control (with a JMP instruction) to the entry point of the 
device driver’s start-I/O routine 


The newly activated driver fork process executes under the constraints listed 
in Section 3.3.3.2. It executes until one of the following events occurs: 


Device-dependent processing of the I/O request is complete. 


A shared resource needed by the driver is unavailable, as described in 
Section 3.4. 


Device activity requires the fork process to wait for a device interrupt. 


4.2.2 Activating a Device and Waiting for an Interrupt 


Depending on the device type supported by the driver, the start-I/O routine 
performs some or all of the following steps: 


1 


2 


8 


9 


Analyzes the I/O function and branches to driver code that prepares the 
UCB and the device for that 1/O operation 


Copies the contents of fields in the IRP into the UCB 


Tests fields in the UCB to determine whether the device and/or volume 
mounted on the device are valid 


If the device is attached to a multiunit controller, obtains the controller 
data channel 


If the I/O operation is a DMA transfer, obtains 1/O adapter resources 
such as map registers and a UNIBUS adapter buffered data path 


Raises IPL to device IPL, obtaining the associated device lock in a VMS 
multiprocessing environment, to synchronize its access to device registers 


Loads all necessary device registers except for the device’s control and 
status register (CSR) 


Raises IPL to IPL$_POWER and confirms that a power failure that would 
invalidate the device operation has not occurred on the local processor 


Loads the device’s CSR to activate the device 


10 Invokes a VMS routine (using either the WFIKPCH or WFIRLCH macro) 


to suspend the driver fork process until a device interrupt or timeout 
occurs 


This routine (IOC$6WFIKPCH or IOC$WFIRLCH) expects to find, among 
the items it inherits on the stack, the driver’s fork IPL, as placed there by 
the start-I/O routine in step 7. As it suspends the driver, IOCSWFIKPCH 
or IOC$WFIRLCH saves the driver’s context in the UCB’s fork block. This 
context consists of the following information: 


The contents of R3 and R4 (UCB$L__FR3, UCB$L_FR4) 
The implicit contents of R5 as the address of the UCB 
A driver return address (UCB$L_FPC) 
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e The relative offset to a device timeout handler (calculated from UCB$L— 
FPC and the value specified in the invocation of the WFIKPCH or 
WFIRLCH macro) 


e¢ The time at which the device will time out (UCB$L_DUETIM) 


By convention, R4 often contains the address of the CSR; it permits the driver 
to examine device registers. When the driver fork process regains control after 
interrupt processing, R5 contains the UCB address; it is the key to the rest of 
the I/O database that is relevant to the current I/O operation. 


Having removed the driver's start-I/O routine’s return address from the 
stack and stored it in UCB$L_FPC, IOC$6WFIKPCH (or IOC$WFIRLCH) 
issues a DEVICEUNLOCK macro that restores IPL to fork IPL from the 
stack. It then exits with an RSB instruction. Thus, IOCSWFIKPCH (or 
IOC$WFIRLCH) effectively passes control to the caller of its caller. In this 
case, the caller of the driver start-I/O routine is EXE$INSIOQ. The flow back 
from EXE$INSIOQ to a user process that asynchronously requested the I/O 
operation is shown in Figure 4-2. 


You can find additional information on the context of a start-I/O routine in 
Chapter 8. 


4.2.3 Handling a Device Interrupt 


When the device requests an interrupt, the interrupt dispatcher transfers 

control to the driver interrupt service routine. The driver’s interrupt service 
routine runs at a high IPL so that the routine can service interrupts quickly. 
A driver interrupt service routine usually performs the following processing: 


1. Retrieves the address of the UCB that owns the controller from IDB$L — 
OWNER 


2 Issues the DEVICELOCK macro to obtain the device lock associated with 
operations at device IPL in a VMS multiprocessing environment 


3 For multiunit device controllers, determines which device unit generated 
the interrupt 


4 Examines the UCB for the device to confirm that the driver fork process 
expects the interrupt 


5 Saves device registers 


6 Reactivates the suspended driver fork process 


If necessary, the reactivated driver fork process executes at the high IPL of 
the interrupt service routine for a few instructions. Very soon, however, 
the driver lowers its execution priority so that it does not block subsequent 
interrupts for other devices in the system. 


4.2.4 Switching from Interrupt to Fork Process Context 


To lower its priority, the driver calls a VMS fork process queuing routine (by 
means of the IOFORK macro) that performs the following actions: 


1 Disables the timeout that was specified in the wait-for-interrupt routine 
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2 Saves R3 and R4 (UCB$L_FR3, UCB$L_FR4) 


3 Saves the address of the instruction following the IOFORK request in the 
UCB fork block (UCB$L_FPC) 


4 Places the address of the UCB fork block from R5 in a processor-specific 
fork queue for the driver’s fork level 


5 Returns to the driver’s interrupt service routine 


The interrupt service routine then cleans up the stack, issues the 
DEVICEUNLOCK macro to release the device lock, restores registers, and 
dismisses the interrupt. Figure 4-7 illustrates the flow of control in a driver 
that creates a fork process after a device interrupt. 


Figure 4—7 Creating a Fork Process After an Interrupt 
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4.2.5 Activating a Fork Process from a Fork Queue 


When no higher priority interrupts are pending, the local processor transfers 
control to the fork dispatcher. When the processor grants an interrupt at a 
fork IPL, the fork dispatcher processes the local fork queue that corresponds 
to the IPL of the interrupt. To do so, the dispatcher performs these actions: 


1 Removes a fork block from the fork queue 
2 _ Restores fork context 
3 Obtains the fork lock specified in the fork block 


4 Transfers control back to the fork process 
Thus, the driver code calls VMS code that coordinates suspension and 
restoration of a driver fork process. This convention allows VMS to service 


hardware device interrupts in a timely manner and reactivate driver fork 
processes as soon as no device requires attention. 
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When a given fork process completes execution, the fork dispatcher releases 
the fork lock and removes the next entry, if any, from the local fork queue. 
This fork dispatcher repeats the sequence described previously until the 
fork queue is empty. After servicing the last entry in the queue, the fork 
dispatcher releases the fork lock, restores RO through R5 from the stack, and 
dismisses the interrupt with an REI instruction. 


Figure 4-8 illustrates the reactivation of a driver fork process. 


Figure 4-8 Reactivation of a Driver Fork Process 
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4.3 Completing an I/O Request 
Once reactivated, a driver fork process completes the I/O request as follows: 


1 Releases shared driver resources, such as map registers, UNIBUS adapter 
buffered data path, and controller ownership 


2 Returns status to the VMS I/O completion routine 


The I/O-completion routine performs the following steps to start 
postprocessing of the I/O request and to start processing the next I/O request 
in the device’s queue: 


1. Writes return status from the driver into the IRP 


2 Inserts the finished IRP in the local processor’s I/O-postprocessing queue 
and requests an interrupt from the processor at IPL$_IOPOST 


3 Creates a new fork process for the next IRP in the device’s pending-I/O 
queue 


4 Activates the new driver fork process 


4.3.1  1/O Postprocessing 


When the local processor’s IPL drops below the I/O postprocessing IPL, the 
processor dispatches to the I/O postprocessing interrupt service routine. This 
VMS routine completes device-independent processing of the I/O request. 


Using the IRP as a source of information, the IPL$_IOPOST dispatcher 
executes the following sequence for each IRP in the postprocessing queue: 


1 Removes the IRP from the queue 


2 If the I/O function was a direct I/O function, adjusts the issuing process’s 
direct I/O quota and unlocks the pages involved in the I/O transfer 


3 If the I/O function was a buffered I/O function, adjusts the issuing 
process’s buffered I/O quota and, if the I/O was a write function, 
deallocates the system buffers used in the transfer 


4 Posts the local event flag associated with the I/O request 


5 Queues a special kernel-mode AST routine to the process that issued the 
$QIO system service call 


4-17 


Overview of I/O Processing 
4.3 Completing an I/O Request 


4-18 


The queuing of a special kernel-mode AST routine allows I/O postprocessing 
to execute in the context of the user process but in a privileged access mode. 
Process context is needed to return the results of the I/O operation to the 
process’s address space. The special kernel-mode AST routine sets any 
common event flag associated with the I/O request and writes the following 
data into the process’s address space: 


¢ Data read in a buffered I/O operation 
e If specified in the I/O request, the contents of the diagnostic buffer 
e If specified in the I/O request, the two longwords of I/O status 


If the I/O request specifies an I/O completion AST routine, the special 
kernel-mode AST routine queues the I/O completion AST for the process. 
When VMS delivers the I/O completion AST, the system AST delivery 
routine deallocates the IRP. The first part of an IRP is the AST control block 
for user requested ASTs. 





Part II Writing a Device Driver 


Device drivers consist of static tables, routines that perform I/O 
preprocessing, and routines that handle the device and controller. The 
chapters that follow describe how to write the following sections of a 
driver: 


Static tables 
Routines that use the device driver's function decision table (FDT) 


Routines that start an |/O operation on the device and complete the 
1/O operation 


Routines that handle interrupts 
Routines that initialize devices and controllers 
Routines that cancel an |/O operation 


Routines that log errors 


The “how to” chapters are preceded by a chapter that contains a driver 
template. The template illustrates the general organization and writing of a 
driver. 


Note that the “how to” chapters describe a common approach to the 
design of various driver routines; they are examples. They do not present 
the only approach that can be taken to writing a driver. 


F —s Template for a Device Driver 


The pages that follow describe conventions to be used by device drivers 
and provide a template for a device driver. Drivers do not necessarily need 
all of the routines indicated by the template, nor do driver routines and 
tables need to follow the exact order of the template. However, the VMS 
operating system does place a few restrictions on the order and content of 
driver routines and tables. 


Figure 5-1 illustrates the organization of a device driver. The first item in a 
device driver is the driver prologue table and the second is usually the driver 
dispatch table. The order of the remaining driver components varies from 
driver to driver. 


The last statement in every driver, except for the .END assembly directive, 
must be a label marking the end of the driver. The address of this label 
is stored in the driver prologue table. The driver-loading procedure uses 
this address to calculate the size of the driver. Chapter 15 describes the 
driver-loading procedure. 


Some drivers contain no device-dependent, FDT routines. Other drivers 
need only minimal initialization procedures. However, every driver normally 
contains static driver tables and a start-I/O routine or an interrupt service 
routine. 





5.1 Coding Conventions 


The driver-loading procedure loads a device driver into a block of nonpaged 
system memory whose location is chosen by the operating system memory 
allocation routines. Therefore, the driver must consist of position-independent 
code only. 


In addition, the system might call a device driver repeatedly to process 

I/O requests and interrupts. The driver often does not complete one I/O 
operation before the system transfers control to the driver to begin another on 
a different unit. For this reason, the code must be reentrant. 


The rules of position-independent and reentrant code are as follows: 


¢ Instructions can branch only to relative addresses within the driver and to 
global addresses listed in the VMS symbol table (SYS$SYSTEM:SYS.STB). 


¢ Static tables can list only global addresses and relative addresses within 
the driver. 


e The driver cannot store temporary data in local driver tables for dynamic 
driver context. All dynamic temporary storage must be contained within 
the unit control block corresponding to an I/O request or the current I/O 
request block. 


e The driver must refer to the I/O database by loading the address of a 
data structure into a general register and using displacement addressing 
to the fields of the data structure. 
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Figure 5-1 Driver Organization 
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Device drivers must also restrict their use of general registers and the stack: 


FDT routines can use RO through R2 and R9 through R11 as available 
registers. The routines can use other registers by saving the registers 
before use and restoring them before exiting from the FDT routine. 


All other driver routines can use RO through R5 as available registers. 
The routines can use other registers, if necessary, by saving and restoring 
them; but using other registers in this way is discouraged. 


All driver routines can use the stack for temporary storage only if the 
routines restore the stack to its previous state before calling any VMS 
routines, forking, or executing RSB instructions. 
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Because certain VAX processors and VMS cooperate to support the emulation 
of specific sets of VAX instructions, a device driver writer should exercise 
some caution. Because the software emulation for floating-point instructions 
may at some time be placed in pageable code, drivers should never use 
floating-point instructions. VMS only guarantees the emulation for character 
string instructions to be nonpaged. 


5.2 Restrictions on the Use of Device-Register I/O Space 


The programmer of a device driver must observe the following restrictions on 
the use of device registers: 


Drivers should always store the address of a device control register in 
a general register and then gain access to the device register indirectly 
through the general register. The following example defines symbolic 
word offsets for each device register and gains access to them using 
displacement-mode addressing from R4. 


; Device register offsets 


LP_CSR = 0 ; CSR offset 
LP_DBR = 2 ; Buffer address offset 
MOVL  UCB$L_CRB(R5) ,R4 ; Get address of CRB 


MOVL @CRB$L_INTD+VEC$L_IDB(R4) ,R4 ; Get the address of 
; the device's CSR 


TSTW  LP_CSR(R4) ; Is printer on line? 


Floating-point, field, queue, quadword, and octaword operands are not 
allowed in I/O address space, nor can an instruction obtain the position, 
size, length, or base of an operand from I/O space. For example, a driver 
cannot use a bit field instruction to test a bit in a device register. 


Drivers cannot use string-handling instructions when referring to I/O 
space. 


Drivers can use only those instructions that modify or write to a 
maximum of one destination. The destination must be the last operand. 


Registers of devices connected to the backplane interconnect (for example, 
UNIBUS adapter device registers and MASSBUS device registers) are 
longwords. Registers of devices connected to the UNIBUS or Q22 bus 
are words. Instructions that refer to UNIBUS adapter registers must use 
longword context. All driver instructions that affect UNIBUS or Q22 bus 
device registers must use word context (for example, BISW, MOVW, and 
ADDWS3) unless the register is byte addressable. 
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An instruction that refers to 1/O space must not generate an exception or 
be interruptable. If the instruction is allowed to restart, it will reread the 
device register, which can cause undesirable device side effects or data 
loss. 


On any given VAX processor, a device driver cannot anticipate the 
completion of an instruction that writes to I/O space before subsequent 
instructions execute. The processor can continue to execute without 
waiting for the data to reach its intended destination. 


Among the consequences of this behavior are the following: 


— Ifa driver initiates device actions that result in an interrupt from the 
device, the amount of time before that interrupt actually occurs is 
unpredictable. 


— Ifa driver disables interrupts from a device, the time before that 
device can no longer generate an interrupt is unpredictable. 


— AnI/O bus error will not be reported synchronously with the 
instruction causing the error. 


As a result, a driver’s interrupt service routine always should be 
prepared to service unexpected or spurious interrupts. See Section 9.3 
for additional discussion of the servicing of unexpected interrupts. 


To access I/O space, use only the following instructions. These 
instructions cannot be interrupted unless they use autoincrement-deferred 
addressing mode or any of the displacement-deferred modes when 
specifying an operand. 


ADAWI ADD(B,W,L)2 ADD(B,W,L)3 
ADWC BIC(B,W,L)2 BIC(B,W,L)3 
BICPSW BIS(B,W,L)2 BIS(B,W,L)3 
BISPSL BISPSW BIT(B,W,L) 
CASE(B,W,L) CHM(K,E,S,U) CLR(B,W.,L) 
CMP(B,W,L) CVT(BW,BL,WB, DEC(B,W,L) 
WL,LB,LW) 
INC(B,W,L) MCOM(B,W,L) MFPR 
MNEG(B,W,L) MOV(B,W._L) MOVA\(B,W.,L) 
MOVAQ MOVPSL MOVZ(BW,BL,WL) 
MTPR PROBE(R,W) PUSHA(B,W.,L) 
PUSHAQ PUSHL SBWC 
SUB(B,W,L)2 SUB(B,W,L)3 TST(B,W,L) 
XOR(B,W,L)2 XOR(B,W,L)3 
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5.3 Implementing Conditional Code in a Driver 


When writing a DMA driver to function for equivalent devices on different 
I/O bus implementations, you should use the ADPDISP macro in code paths 
that need to differentiate between the systems. 


The ADPDISP macro (defined in SYS$LIBRARY:LIB.MLB) provides a means 
by which a device driver can be designed to drive a similar device in a variety 
of VAX configurations. The ADPDISP macro allows the driver to determine 
at run time the existence of a certain I/O bus or adapter characteristic, and 
transfer control to code designed to execute given this hardware trait. 


A driver can use ADPDISP to transfer control to specific code given any of 
the following characteristics: 


e Adapter type 

¢ Number of adapter address bits (18 or 22) 

¢ Map registers supported 

e Autopurging data paths supported 

¢ Buffered data paths supported 

e Direct-vector interrupt dispatching supported 

¢ Odd-aligned transfers on buffered data path supported 
¢ Odd-aligned transfers on direct data path supported 

e Alternate set of map registers (496 to 8191) available 

¢ Q22 bus device 


Use ADPDISP when it is necessary to conditionally execute pieces of code, 
for instance, the allocation and loading of map registers for devices for which 
map registers are available or the allocation of a physically contiguous buffer 
for a DMA transfer on the MicroVAX I (which cannot map such a transfer). 
VMS supplies a similar macro, CPUDISP, which causes a run-time transfer 
of control to a specified destination depending on the CPU type of the 
executing processor. For those processors not uniquely identified by CPU 
type, CPUDISP also provides the means to dispatch on a particular CPU 
subtype. : 


Because a device driver cannot make assumptions about the I/O architecture 
of any given VAX system, DIGITAL recommends that most instances of the 
CPUDISP macro be replaced by an appropriate usage of the ADPDISP macro. 


Appendixes E and F contain examples of drivers that use the ADPDISP 
macro to provide conditional code in a driver. See also the description of the 
ADPDISP macro in Appendix B. 
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Driver Template 


The following pages list the VMS template driver. The code in the 
template can serve as a starting point for a new UNIBUS or Q22 bus 
device driver. You can obtain a machine-readable copy of it from 
SYS$EXAMPLES:TDRIVER.MAR. 


.TITLE TDRIVER - VAX/VMS TEMPLATE DRIVER 
IDENT 'X-2' 


5 AR A A OR A Ee Oe 2 2 ER A AR AG A 2 2 RO 2 eR A I 2 Oe 2 28 2K ge 2 2 2 OK 


COPYRIGHT (c) 1978, 1980, 1982, 1984 BY 
DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASSACHUSETTS. 
ALL RIGHTS RESERVED. 


THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED 
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE 
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER 
COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY 
OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY 
TRANSFERRED . 


* %¥ *¥ Ke ¥ *®¥ Ke Ke Ke Ke He Ke HF KF KF KF KF KH 


THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE 
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT 
CORPORATION. 


DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS 
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL. 


*¥ ¥ eee ee He He He He FH HK KH ¥ 
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t++ 

: FACILITY: 

Z VAX/VMS, Template driver 

; ABSTRACT: 

: This module contains the outline of a driver: 

; Models of driver tables 

: Controller and unit initialization routines 
: An FDT routine 

d The start I/O routine 

: The interrupt service routine 

: The cancel I/O routine 

; The device register dump routine 

; AUTHOR: 

: S. Programmer 11-NOV-1979 

; REVISION HISTORY: 


: X-2 JHPOO2 J. Programmer 21-Aug-1987 
; Add SMP support. 


; vo2 JHPOO1 J. Programmer 2-Aug-1979 11:27 
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: Remove BLBC instruction from CANCEL routine. 


; VO2-001 ROWOO67 R. Programmer 11-Feb-1981 13:10 
; Add description of reason argument to CANCEL routine. 
; Correct references to channel index number. 


.SBTTL External and local symbol definitions 


; External symbols 


$CANDEF ; Cancel reason codes 
$CRBDEF ; Channel request block 
$DCDEF ; Device classes and types 
$DDBDEF ; Device data block 
$DEVDEF ; Device characteristics 
$IDBDEF ; Interrupt data block 
$IODEF ; I/O function codes 
$IPLDEF ; Hardware IPL definitions 
$IRPDEF ; 1/0 request packet 
$SSDEF ; System status codes 
$UCBDEF ; Unit control block 
$VECDEF ; Interrupt vector block 


; Local symbols 
; Argument list (AP) offsets for device-dependent QIO parameters 


Pt = 0 ; First QIO parameter 
P2 = 4 ; Second QIO parameter 
P3 = 8 ; Third QIO parameter 
P4 = 12 ; Fourth QIO parameter 
P5 = 16 ; Fifth QIO parameter 
P6 = 20 ; Sixth QIO parameter 


; Other constants 


1024 ; Default buffer size 


TD_DEF_BUFSIZ = 
TD_TIMEOUT_SEC = 10 ; 10-second device timeout 
TD_NUM_REGS = 4 ; Device has 4 registers 


; Definitions that follow the standard UCB fields 


. 
’ 


$DEFINI UCB ; Start of UCB definitions 
. =UCB$K_LENGTH ; Position at end of UCB 
$DEF UCB$W_TD_WORD ; A sample word 
._BLKW t 
$DEF UCB$W_TD_STATUS ; Device's CSR register © 
. BLKW 1 
$DEF UCB$W_TD_WRDCNT ; Device's word count register 
.BLKW i 
$DEF UCB$W_TD_BUFADR ; Device's buffer address 
-BLKW 1 ; register 
$DEF UCB$W_TD_DATBUF ; Device's data buffer register 
._BLKW 1 
$DEF UCB$K_TD_UCBLEN ; Length of extended UCB 
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; Bit positions for device-dependent status field in UCB 


$VIELD UCB,0,<- ; 


<BIT_ZERO, ,M>,- , 
<BIT_ONE, ,M>,- ; 
> 


$DEFEND UCB ; 


Device status 
First bit 
Second bit 


End of UCB definitions 


; Device register offsets from CSR address 


$DEFINI TD i 


$DEF TD_STATUS , 
-BLKW 1 


; Bit positions for device control/status 
-VIELD TD_STS,0,<- ; 
<GO, ,M>,- ; 
<BIT1, ,M>,- ; 
<BIT2, ,M>,- ; 
<BIT3, ,M>,- ; 
<XBA,2,M>,- ; 
<INTEN, ,M>,- ; 
<READY, ,M>, - ; 
<BIT8, ,M>,- : 
<BIT9, ,M>,- ; 
<BIT10, ,M>,- ; 
<BIT11, ,M>,- ; 
<,1>,- 
<ATTN, ,M>,- i 
<NEX, ,M>, - ; 
<ERROR, ,M>, - ; 
> 


$DEF TD_WRDCNT ; 


._BLKW 1 

$DEF TD_BUFADR ; 
._BLKW 1 

$DEF TD_DATBUF ; 
._BLKW i 


$DEFEND TD ; 


.SBTTL Standard tables 
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Start of status definitions 


Control/status 


register 


Control/status register 
Start device 

Bit one 

Bit two 

Bit three 

Extended address bits 
Enable interrupts 

Device ready for command 
Bit eight 

Bit nine 

Bit ten 

Bit eleven 

Disregarded bit 
Attention bit 
Nonexistent memory flag 
Error or external interrupt 


Word count 
Buffer address 


Data buffer 


End of device register 
definitions 


; Driver prologue table 


DPTAB - 
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END=TD_END , - ; 
ADAPTER=UBA, - ; 
UCBSIZE=<UCB$K_TD_UCBLEN>, - : 
NAME=TDDRIVER ; 


DPT_STORE INIT 


DPT_STORE REINIT 


4 Driver Template 


DPT-creation macro 
End of driver label 
Adapter type 
Length of UCB 
Driver name 

Start of load 


; initialization table 

DPT_STORE UCB,UCB$B_FLCK,B,SPL$C_IOLOCKS8 ; 

DPT_STORE UCB,UCB$B_DIPL,B, 22 ; 

DPT_STORE UCB,UCB$L_DEVCHAR ,L, <- : 
DEV$M_IDV! - ; 
DEV$M_ODV> : 

DPT_STORE UCB,UCB$B_DEVCLASS,B,DC$_SCOM  ; 

DPT_STORE UCB,UCB$W_DEVBUFSIZ,W,- i 
TD_DEF_BUFSIZ 


DPT_STORE DDB ,DDB$L_DDT ,D, TD$DDT : 
DPT_STORE CRB ,CRB$L_INTD+VEC$L_ISR,D, - ; 
TD_INTERRUPT ; 


DPT_STORE CRB, - 


CRB$L_INTD+VEC$L_INITIAL, - a 
D,TD_CONTROL_INIT 


DPT_STORE CRB, - 


CRB$L_INTD+VEC$L_UNITINIT, - ; 
D,TD_UNIT_INIT : 


DPT_STORE END 


; Driver dispatch table 


DDTAB - 


DEVNAM=TD, - : 


START=TD_ 


START , - ; 


FUNCTB=TD_FUNCTABLE, - , 
CANCEL=TD_CANCEL, - ; 
REGDMP=TD_REG_ DUMP : 


Device FORK LOCK 
Device interrupt IPL 
Device characteristics 
input device 
output device 
Sample device class 
Default buffer size 


Start of reload 
initialization table 
Address of DDT 
Address of interrupt 
service routine 
Address of controller 
initialization routine 


Address of device 
unit initialization 
routine 


End of initialization 
tables 


DDT-creation macro 
Name of device 

Start I/0 routine 

FDT address 

Cancel I/O routine 
Register dump routine 
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; Function decision table 


TD_FUNCTABLE : 
FUNCTAB 


FUNCTAB 
FUNCTAB 


FUNCTAB 


FUNCTAB 


<READVBLK, 
READLBLK  - 
READPBLK , - 
WRITEVBLK, 
WRITELBLK, 
WRITEPBLK, 
SETMODE, - 

SETCHAR> 

+EXE$READ , 
<READVBLK, 
READLBLK , - 
READPBLK> 

+EXE$WRITE 
<WRITEVBLK 
WRITELBLK, 
WRITEPBLK> 


’ 
’ 


+EXE$SETMODE , - i 


<SETCHAR, - 
SETMODE> 


. 
: 


FDT for driver 

Valid I/O functions 
Read virtual 

Read logical 

Read physical 

Write virtual 

Write logical 

Write physical 

Set device mode 

Set device chars 

No buffered functions 
FDT read routine for 
read virtual, 

read logical, 

and read physical 
FDT write routine for 
write virtual, 

write logical, 

and write physical 
FDT set mode routine 
for set chars and 
set mode 


.SBTTL TD_CONTROL_INIT, Controller initialization routine 


ttt 


; TD_CONTROL_INIT, Readies controller for I/0 operations 


; Functional description: 


: The operating system calls this routine in 3 places: 


; Inputs: 

: R4 
: R5 
: R6 
: R8 


; Outputs: 


at system 


startup 


during driver loading and reloading 
during recovery from a power failure 


- address 
- address 
- address 
- address 


of the CSR (controller status register) 
of the IDB (interrupt data block) 

of the DDB (device data block) 

of the CRB (channel request block) 


; The routine must preserve all registers except RO-R3. 


TD_CONTROL_INIT 
RSB 


; Initialize controller 


; Return 


.SBTITL TD_UNIT_INIT, Unit initialization routine 
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; TD_UNIT_INIT, Readies unit for I/O operations 


; Functional description: 


: The operating system calls this routine after calling the 
: controller initialization routine: 


; at system startup 
; during driver loading 
; during recovery from a power failure 


; Inputs: 

: R4 - address of the CSR (controller status register) 
: R5 - address of the UCB (unit control block) 

; Outputs: 


; The routine must preserve all registers except RO-R3. 


TD_UNIT_INIT: ; Initialize unit 
BISW #UCB$M_ONLINE, - 
UCB$W_STS(R5) ; Set unit online 
RSB ; Return 


.SBTTL TD_FDT_ROUTINE, Sample FDT routine 


++ 


; TD_FDT_ROUTINE, Sample FDT routine 


; Functional description: 


; T.B.S. 
; Inputs: 
; RO-R2 - scratch registers 
; R3 ~ address of the IRP (1/0 request packet) 
; R4 - address of the PCB (process control block) 
; R5 - address of the UCB (unit control block) 
; R6 - address of the CCB (channel control block) 
: R7 - bit number of the I/0 function code 
; R8 ~ address of the FDT table entry for this routine 
; RQ-R11 - scratch registers 
; AP - address of the ist function dependent QIO parameter 
; Outputs: 
; The routine must preserve all registers except RO-R2, and 
; RQ-Ri1. 
TD_FDT_ROUTINE: ; Sample FDT routine 
RSB ; Return : 


.SBTTL TD_START, Start I/O routine 
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++ 


; TD.START - Start a transmit, receive, or set mode operation 
; Functional description: 


: T.B.S. 

; Inputs: 

: R3 - address of the IRP (I/0 request packet) 

i R5 - address of the UCB (unit control block) 

; Outputs: 

H RO - 1st longword of I/0 status: contains status code and 
; number of bytes transferred 

Ri - 2nd longword of I/O status: device-dependent 


: The routine must preserve all registers except RO-R2 and R4. 


TD_START: ; Process an I/0 packet 
DEVICELOCK LOCKADDR=UCB$L_DLCK(R5),- ; Lock device access. 
SAVIPL=- (SP) ; Save current IPL 


WFIKPCH TD_TIMEOUT , #TD_TIMEOUT_SEC 
; After a transfer completes successfully, return the number of bytes 
; transferred and a success status code. 


IOFORK 

INSV UCB$W_BCNT(R5) , #16, - ; Load number of bytes trans- 
#16 ,RO ; ferred into high word of RO. 

MOVW #SS$_NORMAL , RO ; Load a success code into RO. 


; Call I/O postprocessing. 
COMPLETE_IO: ; Driver processing is finished. 
REQCOM ; Complete I/O. 


; Device timeout handling. Return an error status code. 


s 


TD_TIMEOUT : ; Timeout handling 
DEVICEUNLOCK LOCKADDR=UCB$L_DLCK(R5),- ; Unlock device access 
NEWIPL=#8 , - ; Lower IPL 
PRESERVE=NO ; Don't preserve RO 
MOVZWL #SS$_TIMEOUT, RO ; Return error status 
BSBB COMPLETE_IO ; Call I/0 postprocessing 
DEVICELOCK LOCKADDR=UCB$L_DLCK(R5),- ; Acquire device lock for exit 


PRESERVE=NO 
RSB 


SBITL TD_INTERRUPT, Interrupt service routine 


i++ 
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; TD_LINTERRUPT, Analyzes interrupts, processes solicited interrupts 


; Functional description: 


The sample code assumes either 


Inputs: 
O(SP) 


4(SP) 
8(SP) 
12(SP) 
16 (SP) 
20(SP) 
24 (SP) 
28 (SP) 
32(SP) 


The IDB 


Outputs: 


that the driver is for a single-unit controller, and 
that the unit initialization code has stored the 
address of the UCB in the IDB; or 


that the driver's start I/O routine acquired the 
controller's channel with a REQPCHAN macro call, and 
then invoked the WFIKPCH macro to keep the channel 
while waiting for an interrupt. 


- pointer to the address of the IDB (interrupt data 
block) 

- saved RO 

- saved Ri 

~ saved R2 

- saved R3 

- saved R4 

- saved R5 

- saved PC 

- saved PSL (processor status longword) 


contains the CSR address and the UCB address. 


The routine must preserve all registers except RO-R5. 


TD_INTERRUPT : 


; Service device interrupt 


MOVL @(SP)+,R4 ; Get address of IDB and remove 
; pointer from stack 
ASSUME IDB$L_CSR EQ 0O 
ASSUME IDB$L_OWNER EQ 4 
MOVQ IDB$L_CSR(R4) , R4 ; Get address of device's CSR 
; Get address of device owner's UCB 
DEVICELOCK LOCKADDR=UCB$L_DLCK(R5), - ; Lock device access 
PRESERVE=NO, - ; Don't preserve RO 
CONDITION=NOSETIPL ; Don't bother setting our IPL 
BBCC #UCB$V_INT, - ; If device does not expect 
UCB$W_STS (R5) , - ; interrupt, dismiss it 


UNSOL_INTERRUPT 


; This is a solicited interrupt. Save 


MOVW 


MOVW 


MOVW 


MOVW 


; the contents of the device registers in the UCB. 


TD_STATUS (R4) , - ; Otherwise, save all device 
UCB$W_TD_STATUS (R5) ; registers. First the CSR 
TD_WRDCNT (R4) , - ; Save the word count register 
UCB$W_TD_WRDCNT (R5) 

TD_BUFADR (R4) , - ; Save the buffer address 
UCB$W_TD_BUFADR (R5) ; register 

TD_DATBUF (R4) , ~ ; Save the data buffer register 


UCB$W_TD_DATBUF (R5) 


5-13 


Template for a Device Driver 
5.4 Driver Template 


5-14 


; Restore control to the main driver 


* 
, 


RESTORE_DRIVER: ; Jump to main driver code 
MOVL UCB$L_FR3(R5) ,R3 ; Restore driver's R3 (use a 
; MOVQ to restore R3-R4) 
JSB @UCB$L_FPC (R5) ; Call driver at interrupt 


; wait address 


; Dismiss the interrupt 


UNSOL_INTERRUPT: ; Dismiss unsolicited interrupt 
DEVICEUNLOCK LOCKADDR=UCB$L_DLCK(R5),- ; Unlock device access 
PRESERVE=NO ; Don't bother preserving RO 
POPR #°M<RO,R1,R2,R3,R4,R5> ; Restore RO-R5 
REI ; Return from interrupt 


.SBTTL TD_CANCEL, Cancel I/O routine 
++ 
; TD_CANCEL, Cancels an I/O operation in progress 


; Functional description: 


; This routine calls IOC$CANCELIO to set the cancel bit in the 
; UCB status longword if: 


: the device is busy, 
; the IRP's process ID matches the cancel process ID, 
: the IRP channel matches the cancel channel. 


: If IOC$CANCELIO sets the cancel bit, then this driver routine 
: does device-dependent cancel I/0 fixups. 


; Inputs: 

; R2 - channel index number 

; R3 - address of the current IRP (1/0 request packet) 

: R4 - address of the PCB (process control block) for the 

; process canceling I/0 

; R5 - address of the UCB (unit control block) 

; R8 - cancel reason code, one of: 

: CAN$C_CANCEL if called through $CANCEL or 

: $DALLOC system service 

: CAN$C_DASSGN if called through $DASSGN system 
: service 

: These reason codes are defined by the $CANDEF macro. 
; Outputs: 


; The routine must preserve all registers except RO-R3. 


; The routine may set the UCB$V_CANCEL bit in UCB$W_STS. 


’ 


TD_CANCEL: ; Cancel an I/O operation 
JSB G* IOC$CANCELIO ; Set cancel bit if appropriate. 
BBC #UCB$V_CANCEL, - ; If the cancel bit is not set, 
UCB$W_STS(R5) , 10$ ; just return. 
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; Device-dependent cancel operations go next. 


; Finally, the return. 
10$: 
RSB ; Return 


.SBTTL TD_REG_DUMP, Device register dump routine 


,++ 


; TD_REG_DUMP, Dumps the contents of device registers to a buffer 


; Functional description: 


; Writes the number of device registers and their current 
; contents into a diagnostic or error buffer. 


; Inputs: 
4; RO - address of the output buffer 
; R4 - address of the CSR (controller status register) 
: R5 - address of the UCB (unit control block) 
; Outputs: 


; The routine must preserve all registers except R1-R3. 


; The output buffer contains the current contents of the device 
; registers. RO contains the address of the next empty longword in 
; the output buffer. 


TD_REG_DUMP : ; Dump device registers 

MOVZBL #TD_NUM_REGS, (RO)+ ; Store device register count 

MOVZWL UCB$W_TD_STATUS(R5),-  ; Store device status register 
(RO) + 

MOVZWL UCB$W_TD_WRDCNT(R5),- ; Store word count register 
(RO) + 

MOVZWL UCB$W_TD_BUFADR(R5),- ; Store buffer address register 
(RO) + 

MOVZWL UCB$W_TD_DATBUF (R5) , - ; Store data buffer register 
(RO) + 

RSB ; Return 


.SBTTL TD_END, End of driver 


++ 


; Label that marks the end of the driver 


, 


TD_END: ; Last location in driver 
. END 
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6 Writing Device-Driver Tables 


Every device driver declares three static tables that describe the device and 
driver: 


e Driver prologue table—describes the device type, driver name, and 
fields in the I/O database to be initialized during driver loading and 
reloading. 


¢ Driver dispatch table—lists some of the driver’s entry points to which 
VMS transfers control. The channel request block and function decision 
table list other entry points. 


¢ Function decision table—lists valid functions of the driver and entry 
points to routines that perform I/O preprocessing for each function. 


The VMS operating system provides macros that drivers can invoke to create 
these tables. 





6.1 Driver Prologue Table 


The driver prologue table (DPT) is the first part of every device driver. 
This table, along with parameters to the SYSGEN command that request 
driver loading, describes the driver to the driver-loading procedure. In turn, 
the driver-loading procedure computes the size of the driver, loads it into 
nonpaged system memory, and creates data structures for the new device(s) 
in the I/O database. The loading procedure also links the new DPT into 

a list of all DPTs known to the system. Chapter 15 describes how the 
driver-loading procedure decides which data structures to build for a given 
device. 


Device drivers can pass data-structure initialization information to the driver- 
loading procedure through values stored in the DPT. In addition, the driver- 
loading procedure initializes some fields within the device data structures 
using information from its own tables. 


Figure A-10 illustrates the DPT data structure, and Table A-9 describes its 
contents. Drivers must treat many of the fields initialized by the driver- 
loading procedure as read-only fields. These fields are marked with an 
asterisk in Figure A-10. 


To create a DPT, the driver invokes the DPTAB macro, as described in 
Appendix B. The DPTAB macro generates a driver prologue table (DPT) in a 
program section called $$$105_PROLOGUE. 


The DPTAB macro requires the following information: 
e Address of the end of the driver in its end argument. 


¢ Code identifying the device by its adapter type in the adapter argument. 
- Accepted adapter types include UBA (for devices attached to either a 
UNIBUS or Q22 bus), MBA, and GENBI. 


¢ Name of the driver in the name argument. 
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e Size of the unit control block (UCB) in the ucbsize argument. (The 
template in Section 5.4 and the macro descriptions in Appendix B 
demonstrate how you can specify an extended UCB defined by VMS 
or create an extended UCB within a driver.) 


The DPTAB also allows you to specify the following information, if applicable 
to the device driver: 


e Whether the driver needs a permanently allocated system page 


e Whether the driver has been written to run in a VMS symmetric 
multiprocessing system 


e Name of a driver unloading routine, if any, to be called subject to a 
SYSGEN RELOAD command 


-@ Maximum number of units supported by the driver (default is 8) 


¢ Number of UCBs to be created when the driver is loaded by means of 
the SYSGEN autoconfiguration facility and the address of a unit delivery 
routine to be called by that facility 


A driver follows the DPTAB macro invocation with several instances of 
the DPT_STORE macro. The DPT_STORE macro provides the driver with 
a means of communicating its initialization needs to the driver-loading 
procedure. When invoked, the DPT_STORE macro places information in 
the DPT that the driver-loading procedure uses to load specified values into 
specified fields. The DPT_STORE macro accepts two lists of fields: 


e Fields to be initialized only when the driver is first loaded 


e Fields to be initialized when a driver is first loaded and reinitialized if the 
driver is reloaded 


The DPTAB macro stores the relative addresses of these two lists, called 
initialization and reinitialization tables, in the DPT. 


Drivers use the DPT_STORE macro with the INIT table marker label to 
begin a list of DPT_STORE invocations that supply initialization data for the 
following fields: 


UCB$B_FLCK Index of the fork lock under which the driver performs 
fork processing. The DPTAB macro, in invoking the 
$SPLCODDEF macro, defines the symbols for these 
indexes. 


UCB$B_DIPL Device interrupt priority level. 


Other commonly initialized fields are 


UCB$L_DEVCHAR Device characteristics 
UCB$B_DEVCLASS Device class 
UCB$B_DEVTYPE Device type 


UCB$W_DEVBUFSIZ Default buffer size 
UCB$Q_DEVDEPEND Device-dependent parameters 
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Drivers use the DPT_STORE macro with the REINIT table marker label 

to begin a list of DPT_STORE invocations that supply initialization and 
reinitialization data for certain fields. Every driver must specify the following 
field in such an invocation: 


DDB$L_DDT Driver dispatch table 


Other commonly initialized fields are 


CRB$L_INTD+VEC$L _ISR Interrupt service routine. 
’ CRB$L_INTD2+VEC$L _ISR Interrupt service routine for second interrupt 
vector. 
CRB$L_INTD+VEC$L_INITIAL Controller initialization routine. 


CRB$L_INTD+VEC$L-_UNITINIT Unit initialization routine (for UNIBUS, 022 
bus, and generic VAXBI device drivers). 
Note that MASSBUS drivers must specify 
the address of the unit initialization routine 
in an invocation of the DDTAB macro. 


For an example of the use of the DPT and DPT_STORE macros, see the 
description of the DPTAB macro in Appendix B. 





6.2 Driver Dispatch Table 


The driver dispatch table (DDT) lists some of the entry points for driver 
routines to be called by VMS for I/O processing. Every driver must create a 
DDT. 


The routines listed in the DDT can reside in the driver module or in a VMS 
module. Appendix C describes the VMS device-independent routines that can 
be specified. 


Device-dependent routines are normally located in the driver module. The 
DDT contains relative addresses for routines located in the driver module and 
absolute addresses for routines located in the operating system. At loading 
time, the driver-loading procedure changes the relative addresses of driver 
routines to absolute addresses. 


The driver creates a DDT by invoking the macro DDTAB. The DDTAB macro 
labels the DDT devnam$DDT, according to the value you supply in its 
devnam argument. The driver-loading procedure writes the address of the 
DDT table, as specified in a DPT_STORE macro, into the DDB. Figure A-9 
illustrates the structure of a DDT and Table A-8 describes its contents. 


The DDTAB macro also generates the program section ($$$115_DRIVER) in 
which the DDT itself and all driver code reside. 


The DDTAB macro has a single required argument, functb, for which the 
driver must specify the address of its function decision table. Several optional 
arguments allow the driver to specify the names of the following routines, if 
applicable: 


e  Start-I/O routine 
¢ Unsolicited interrupt service routine (for MASSBUS device drivers) 
e Cancel-I/O routine 


e¢ Register dumping routine 
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e Unit initialization routine 
e Alternate start-I/O routine 


e Cloned UCB routine 


In addition, you specify the length of any diagnostic buffer or error message 
buffer using the DDTAB macro. 


See the description of the DDTAB macro in Appendix B for additional 
information. 





6.3 Function Decision Table 
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The function decision table (FDT) lists codes for I/O functions that are valid 
for the device; indicates whether the functions are buffered-I/O functions; 
and specifies routines to perform preprocessing for particular functions. Every 
device driver must create an FDT containing three or more entries: 


e The list of valid I/O function codes 
e The list of buffered I/O function codes 


e One or more entries each of which specifies all or a subset of I/O function 
codes and the address of a routine that performs I/O preprocessing for 
those function codes 


If no buffered I/O functions are defined for the device, the second entry 
contains an empty list. 


Taken together, the third through last entries in the FDT specify one or 
more FDT routines for each valid I/O function code for the device. The 
FDT routines must terminate the I/O preprocessing for each type of function 
by transferring control out of the $QIO system service and into a routine 
that queues the I/O request to a driver, inserts the I/O request in the 
postprocessing queue, or aborts the I/O request. 


Refer to Chapter 7 for information on the writing of FDT routines. — 


Table 6-1 lists the physical, logical, and virtual I/O function codes defined by 
VMS. Note that certain of the function codes listed have the same values in 
VMS Version 5.0. A complete list of function codes and values is contained 
in the macro $IODEF in SYS$LIBRARY:STARLET.MLB. 


Table 6—1 


Function 
Physical 1!/O 


lO$_NOP 
1\O$_UNLOAD 


IO$_SEEK 


lO$_RECAL 
l\O$_DRVCLR 
lO$_RELEASE 
l|O$_OFFSET 


lIO$_RETCENTER 
lO$_PACKACK 


lIO$_SEARCH 


1IO$_WRITECHECK 
lO$_WRITEPBLK 
l\O$_READPBLK 
l\O$__WRITEHEAD 


1\O$_ _READHEAD 
lO$_WRITETRACKD 


lIO$_READTRACKD 
IO$_AVAILABLE 


lO$_SETPRFPATH 
lO$_DSE 


\O$_REREADN 
l\O$_REREADP 
lOS$_WRITERET 
lO$_READPRESET 
lO$_SETCHAR 
1\O$_SENSECHAR 
lO$_WRITEMARK 
lO$ _WRTTMKR 


l\OS_ FORMAT 


1/O Function Codes 


Description 


No operation 


Unload drive (required by all 
disk drivers) 


Seek cylinder 


Recalibrate drive 
Drive clear 
Release port 
Offset read heads 


Return to. center line 


Pack acknowledgment 
(required by all disk drivers) 


Search for sector 


Write check data 
Write physical block 
Read physical block 
Write header and data 


Read header and data 
Write track data 


Read track data 


Set device available 
(required by all disk drivers) 


Set preferred path 


Data security erase (and 
rewind) 


Reread next 

Reread previous 

Write retry 

Read in preset 

Set device characteristics 
Sense device characteristics 
Write tape mark 

Write tape mark retry 


Format 


Writing Device-Driver Tables 
6.3 Function Decision Table 


Equivalent Symbol(s) 


10$_LOADMCODE 


1O$_SPACEFILE (space files), 10$_STARTMPROC 
(start microprocessor) 


l\O$_STOP (stop) 
IO$_INITIALIZE (initialize) 
l\O$_SETCLOCKP (set clock—physical) 


lO$_ERASETAPE (erase tape), |O$_STARTDATAP 
(start data transfer—physical) 


lO$_QSTOP (queue stop request) 


l\O$_SPACERECORD (space records), |O$_READRCT 
(read replacement and caching table) 


lIO$¢_RDSTATS (read statistics), IO$S__CRESHAD 
(create a shadow set) 


lIO$__ADDSHAD (add member to shadow set) 


1O$_COPYSHAD (perform shadow set copy 
operations) 


1O$_REMSHAD (remove member from shadow set) 


1O$_WRITECHECKH (write check header and data) 
lO$_STARTSPNDL (start spindle) 


lO$_DIAGNOSE (diagnose), IO$_SHADMV (perform 
mount verification on shadow set) 


IO$_CLEAN (clean tape) 
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Table 6—1 (Cont.) 


Function 
Logical 1/O 


l\O$_WRITELBLK 
lO$_READLBLK 
l\O$_REWINDOFF 
l\O$_SETMODE 
lO$_REWIND 
IO$_SKIPFILE 
l\O$_.SKIPRECORD 
lIO$__SENSEMODE 
l\O$_WRITEOF 
lO$_TTY_PORT 
lO$_FLUSH 


Virtual 1/0 


lO$_WRITEVBLK 
lO$__READVBLK 
lO$_ACCESS 
lIO$_CREATE 
1O0$_DEACCESS 
1\O$_DELETE 
lIO$_MODIFY 
lO$__NETCONTROL 


l1O$__READPROMPT 
l\O$__ACPCONTROL 
l\O$_MOUNT 
lO$_TTYREADALL 
lO$_TTYREADPALL 


lIO$__CONINTREAD 


lIO$_CONINTWRITE 


I/O Function Codes 


Description 


Write logical block 

Read logical block 
Rewind and set offline 
Set mode 

Rewind tape 

Skip files 

Skip records 

Sense mode 

Write end of file 

Terminal port FDT routine 


Flush controller cache 


Write virtual block 
Read virtual block 
Access file 


~ Create file 


Deaccess file 
Delete file 
Modify file 


X25 network control 
function 


Read terminal with prompt 
Miscellaneous ACP control 
Mount volume 

Terminal read passall 


Terminal read with prompt 
passall 


Connect to interrupt read- 
only 


Connect to interrupt with 
write 


Equivalent Symbol(s) 


lIO$_FREECAP (return free capacity) 


IO$_SETCLOCK (set clock) 
lIO$_STARTDATA (start data) 


The device driver creates an FDT by invoking the FUNCTAB macro. Each 
invocation of the FUNCTAB macro creates a 2- or 3-longword entry in the 
FDT. The first two invocations create 2-longword entries because they specify 
only function codes; they do not specify an accompanying action routine. 


All subsequent invocations of the FUNCTAB macro must specify both 
function codes and the address of a routine that is to perform preprocessing 
for those functions. These invocations create 3-longword entries. 
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The $QIO system service processes entries in the order in which they appear 
in the FDT. When a function code is present in more than one 3-longword 
entry, the system service sequentially calls every routine specified for the 
function code until a routine stops the scan by aborting, completing, or 
queuing an I/O request. 


See the description of the FUNCTAB macro, and the example of its use, in 
Appendix B for additional information on creating an FDT. 


6.3.1 Defining Buffered-1/O Functions 


The second entry in an FDT is a buffered function bit mask that indicates which 
legal functions the driver handles as buffered-I/O operations. In selecting the 
functions that are to be buffered, you should take the following information 
into consideration: 


e Direct I/O is intended only for devices whose I/O operations always 
complete quickly. For example, although terminal I/O appears fast, users 
can prevent the I/O operation from completing by using CTRL/S to halt 
the operation indefinitely; therefore, terminal I/O operations are buffered 
1/O. 


¢ Use of direct I/O requires that the process pages containing the buffer be 
locked in memory. Locking pages in memory increases the overhead of 
swapping the process that contains the pages. 


¢ Use of buffered I/O requires that the data be moved from the system 
buffer to the user buffer. Moving data requires additional time. 


¢ Routines that manipulate data before delivering it to the user (for 
example, an interrupt service routine for a terminal) cannot gain access 
to the data if direct I/O is used. Therefore, transfers that require data 
manipulation must be buffered I/O. 


e VMS handles the quotas differently for direct I/O and buffered I/O, as 
described in the Guide to Maintaining a VMS System. 


¢ Generally, direct-memory-access (DMA) devices use direct I/O, while 
programmed I/O devices use buffered I/O. 


6.3.2 Defining Device-Specific Function Codes 


You can also define device-specific function codes by equating the name of a 
device-specific function with the name of an existing function that is irrelevant 
to the device. The selected codes should, however, have a type (logical, 
physical, or virtual) that is appropriate for the function they represent. Also, 
user programs that issue $QIO requests specifying a device-specific code must 
similarly redefine the existing function. For example, the assembly code that 
follows defines three device-specific physical I/O function codes. . 


10$_STARTCLOCK=I0$_ERASETAPE ; Start interval clock 
I0$_STOPCLOCK=10$_OFFSET ; Stop interval clock 


I0$_STARTDATA=10$_SPACEFILE ; Start data acquisition 


7 Writing FDT Routines 


The $QIO system service uses the driver’s function decision table (FDT) to 
determine which FDT routines to call to preprocess an I/O request. These 
FDT routines validate process-specified arguments to the $QIO request. VMS 
supplies many device-independent FDT routines. Device drivers contain 
device-dependent FDT routines. 


A driver should call the VMS device-independent FDT routines, described 
in Section 7.5, whenever possible. This practice encourages the use of well 
debugged routines and minimizes driver size. 





7.1 Context of FDT Routine Execution 


The $QIO system service executes in the context of the process that issues 
the I/O request, but in kernel mode and at IPL$_ASTDEL. The process is 
executing in kernel mode because the dispatching of the $QIO system service 
executes a CHMK instruction. Process context allows the $QIO system service 
and driver FDT routines to access perprocess address space. Because the | 
$QIO system service expects FDT routines to preserve this context, an FDT 
routine observes the following conventions: 


¢ It cannot call VMS system services or VMS RMS services. 


e It does not lower IPL below IPL$_ASTDEL. If a routine raises IPL, it 
must obtain any appropriate spin lock, and it must lower IPL to IPL$_ 
ASTDEL before exiting, releasing any acquired spin lock. 


e It does not alter the stack without restoring its original state before 
exiting. 


e If it issues a subroutine call, it must preserve the contents of R3 through 
R8 across the call. It can, however, use RO through R2 and R9 through 
R11 without saving their previous contents. If an FDT routine needs to 
use R3 through R8, it can use the PUSHR and POPR instructions to save 
registers on the stack and later restore them. 


e It exits either by an RSB instruction to return control to the system service, 
or it issues a JMP instruction to one of the VMS routines described in 
Section 7.2.1. 


Before calling an FDT routine, the $QIO system service sets up the contents 
of certain registers, as described in Table 7-1. 


Table 7-1 Registers Loaded by the $QIO System Service 


Register Content 

RO Address of FDT routine being called 

R3 Address of IRP for current I/O request 

R4 Address of process control block (PCB) of current process 
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Table 7—1 (Cont.) Registers Loaded by the $QIO System Service 


Register Content 


R5 Address of UCB of device assigned to user-specified process-!/O 
channel 

R6 Address of CCB that describes user-specified process-l/O channel 

R7 Bit number of user-specified |/O function code 

R8 Address of current entry in FDT 

AP Address of first function-dependent argument (p1) specified in 1/O 
request 


While FDT routines can perform extensive preprocessing, such as determining 
whether user buffers are accessible and reformatting data into buffers in the 
system address space, they should not access device registers because the 
device might be active. Furthermore, FDT routines should exercise restraint 
when modifying the UCB. Routines usually access the UCB while holding 
the associated fork lock at driver fork IPL to synchronize modifications, and 
FDT routines do not execute with such synchronization. Drivers containing 
FDT routines that access device registers or carelessly modify the UCB risk © 
unpredictable operation or a system failure. 





7.2 FDT Routines and Their Exit Paths 


To transfer control to an FDT routine, the $QIO system service loads the 
address of the FDT routine into a register and executes a JSB instruction, as 
follows: 


JSB (RO) 
Each FDT routine chooses an exit path based on the following factors: 


e Whether another FDT routine needs to be called to perform additional 
function-specific processing 


¢ Whether an error is found in the I/O request 
e Whether the operation is complete 


e Whether the I/O operation requires and is ready for device activity 


The FDT routines, as illustrated in Figure 7-1, must transfer control out of the 
FDT processing loop and into a VMS routine that queues an IRP, completes 
an I/O request, or aborts an I/O request. The $QIO system service does 

not stop scanning the FDT. Therefore, you must ensure that for each valid 
function code in a driver’s FDT, there is an FDT routine that does not return 
control to the $QIO system service. 


7.2.1 


FDT Exit Paths 


7.2.1.1 
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Figure 7-1 $QIO Scan of a Function Decision Table 
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An FDT routine can exit using any of the following methods: 
°  RSB | 

e JMP G*EXE$QIODRVPKT 

e¢ JSB G’EXE$ALTQUEPKT 

e¢ JMP G’EXE$FINISHIO or JMP G*EXE$FINISHIOC 

e JMP G’EXE$ABORTIO | 


These methods are described in the following sections, and you can find 
additional details on the routines they involve in Appendix C. 


RSB 

An FDT routine issues an RSB instruction to return to the $QIO system 
service. The FDT routine returns to the system service because the routine 
knows that the FDT contains a subsequent entry with the same function code 
bit set. As a result, the system service searches for another FDT routine. 
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7.2.1.2 


7.2.1.3 


7.2.1.4 


JMP G*EXESQIODRVPKT 

EXE$QIODRVPKT transfers control to a VMS routine that queues an IRP to a 
driver. The FDT routine uses this exit method if all preprocessing is complete, 
if no fatal errors are found in the specification of an I/O request, and if device 
activity, synchronized access to the device’s UCB, or synchronized access to 
device registers is required to complete the I/O request. Common examples 
of such a request are read and write functions. 


EXE$QIODRVPKT transfers control to the device driver's start-I/O 

routine only if the device unit is currently idle. If the device unit is busy, 
EXE$QIODRVPKT inserts the IRP in a priority-ordered queue of IRPs waiting 
for the unit. 


Once an FDT routine transfers control to EXE$QIODRVPKT, no driver code 
that further processes the I/O request can refer to process virtual address 
space. When a device driver’s start-I/O routine gains control, the process that 
queued the I/O request might no longer be the mapped process. Therefore, 
the driver must assume that all information regarding the I/O request is in 
the UCB or the IRP and that all buffer addresses in the UCB are either system 
addresses or page-frame numbers that can be interpreted in any process 
context. 


For direct I/O operations, FDT routines also must have locked all user buffer 
pages in physical memory because paging cannot occur at driver fork level 
or higher interrupt priority levels. The process virtual address space is not 
guaranteed to be mapped again until VMS delivers a special kernel-mode 
AST to the requesting process as part of I/O postprocessing. 


JMP G’EXES$FINISHIO or JMP G*EXESFINISHIOC 

EXE$FINISHIO and EXE$FINISHIOC transfer control to a VMS routine 

that writes a quadword of final I/O status from RO and R1 into the I/O 
status field of the IRP (IRP$L_MEDIA and IRP$L_MEDIA+4). (Note that 
EXE$FINISHIOC clears the second longword of the final I/O status.) The 
routine then inserts the IRP in the I/O postprocessing queue. These routines 
return to the $QIO system service the two longwords of status contained in 
the I/O status block (if any) specified in the I/O request. 


An FDT routine that discovers a device-dependent error should always return 
status using EXE$FINISHIO or EXE$FINISHIOC. These routines gain control 
without any change in process context. Interrupt priority level is at IPL$_ 
ASTDEL,; the process page-tables are mapped; and the process is executing in 
kernel mode. 


JMP G*EXESABORTIO 

EXE$ABORTIO transfers control to a VMS routine that aborts an I/O request. 
An FDT routine that discovers a device-independent error should always use 
this method of exiting. Inability to gain access to a data buffer or an error 

in the specification of the I/O request are examples of device-independent 
errors. 


EXE$ABORTIO gains control without any change in the process context. 
Interrupt priority level is at IPL$_ASTDEL,; the process virtual space is 
mapped; and the process is executing in kernel mode. EXES$ABORTIO stores 
a longword of status in RO and returns this to the system service. 
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7.2.1.5 JSB G*EXESALTQUEPKT 
EXE$ALTQUEPKT transfers control to a VMS routine that calls an alternate 
start-I/O routine in the driver (specified in the driver dispatch table at offset 
DDT$L_ALTSTART) that synchronizes requests for activity on a device unit 
and initiates the processing of I/O requests. 


The FDT routine uses this exit method when it has successfully completed 
all driver preprocessing and the request requires device activity. However, in 
contrast to EXE${QIODRVPKT, EXE$ALTQUEPKT bypasses the device unit’s 
pending-I/O queue and the device busy flag; thus, the driver is activated 
regardless of whether the device unit is busy. A driver that can handle two 
or more I/O requests simultaneously uses this exit method. 


Be aware that programming a device driver to process simultaneous I/O 
requests requires detailed knowledge of VMS internal design. A driver that 
uses EXESALTQUEPKT must not only maintain its internal queues but must 
also synchronize those queues with the unit’s pending-I/O queue, which 

the operating system maintains. In addition, if a driver processes more than 
one IRP at the same time, it must use separate fork blocks. Such a driver 
completes the processing of I/O requests by calling the routine COM$POST. 
This routine places each IRP in a postprocessing queue and returns control to 
the driver. The driver can then fetch another IRP from an internal queue. For 
more information about COM$POST, see Appendix C. 


Unlike the other FDT exit routines, EXES/ALTQUEPKT is called with a JSB 
instruction rather than a JMP instruction. When the alternate start-I/O 
routine finishes, it returns control to EXES,ALTQUEPKT by executing an 
RSB instruction. The FDT routine performs any postprocessing and transfers 
control to the routine EXESQIORETURN. When EXE$QIORETURN gains 
control, it performs the following steps: 


1. Sets the success status code SS$_NORMAL in RO 
2 Lowers the interrupt priority level to zero 


3 Returns (with the RET instruction) to the system service dispatcher 





7.3 FDT Routines for VMS Direct 1/O 


The VMS operating system provides two standard FDT routines that are 
applicable for direct I/O operations: EXE$READ and EXE$WRITE. When 
called by the driver, these routines completely prepare a direct I/O read or 
write request. Thus, a driver that uses these routines eliminates the need for 
its own device-specific FDT routines. 


EXE$READ and EXE$WRITE are described in Section 7.5. 
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7.4 FDT Routines for VMS Buffered |/O 


Device drivers for buffered I/O operations generally contain their own 
device-specific FDT routines. 


An FDT routine for a buffered I/O data transfer operation should confirm 
either read or write access to the user’s buffer and allocate a buffer in system 
space. Sections 7.4.1 and 7.4.2 describe these tasks. 


An FDT routine for a buffered I/O operation that does not involve data 
transfer should copy the function-dependent parameters of the $QIO request 
(p1 to p6) to the IRP, perform any necessary preprocessing, and use one of 
the exit methods listed in Section 7.2.1. 


7.4.1 Checking Accessibility of the User’s Buffer 


First the FDT routine calls EXE$READCHK or EXE$WRITECHK to confirm 
write or read access, respectively, to the user’s buffer. Both of these routines 
write the transfer byte count into IRP$L_BCNT. EXE$READCHK also sets 
IRP$V_FUNC in IRP$W_STS to indicate that the function is a read. 


7.4.2 Allocating the System Buffer 


Next, the FDT routine allocates a system buffer in the following manner: 


1 It adds 12 bytes to the byte count passed in the p2 argument of the user’s 
I/O request, thus accommodating the standard size of a VMS buffer 
header. This is the total system buffer size. 


2 It calls EXESDEBIT_BYTCNT_ALO to ensure that the process’s job has 
sufficient remaining byte count quota to allow its use of the requested 
buffer. If the job has sufficient quota, EXE$DEBIT_BYTCNT_ALO 
allocates the requested buffer from nonpaged pool, writes the buffer’s 
size and type into its third longword, and subtracts the system buffer size 
from JIB$L_BYTCNT. 


VMS also supplies the routines EXE$DEBIT_BYTCNT_BYTLM_ALO, 
EXE$DEBIT_BYTCNT(_NW), EXE$DEBIT_BYTCNT_BYTLM(_NW), and 
EXE$ALLOCBUF which perform the same type of work as EXE$DEBIT_ 
BYTCNT_ALO. These routines are fully described in Appendix C. 


Once the buffer is allocated, the FDT routine takes the following steps: 
1 Loads the address of the system buffer into IRP$L_SVAPTE. 
2 Loads the total size of the system buffer into IRPS5W_BOFF. 


3 Stores the starting address of the system buffer data area in the first 
longword of the buffer header. 


4 Stores the user’s buffer address in the second longword of the header. 


5 Copies data from the user buffer to the system buffer if the I/O request is 
a write operation. 
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At this point, the buffers are ready for the transfer. Figure 7-2 illustrates the 
format of the system buffer. 


Figure 7-2 Format of System Buffer for a Buffered-1/O Read 
Function 
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7.4.3 Buffered-I/O Postprocessing 


When the transfer finishes, the driver returns control to VMS for completion 
of the I/O request. The driver writes the final request status in the low-order 
word of RO. Use of the high-order word of RO and the longword of R1 is 
driver specific. Certain drivers use these fields to report a transfer byte count, 
for example. 


The driver must leave the buffer header intact; 1/O postprocessing relies 
on the header’s accuracy. When VMS I/O postprocessing gains control, it 
performs three steps: 


1 Calls EXE$CREDIT_BYTCNT to add the value in IRP$W_BOFF to JIB$L_ 
BYTCNT, thus updating the user’s byte count quota 


2 If IRP$L_SVAPTE is nonzero, assumes a system buffer was allocated and 
checks to see whether IRP$V_FUNC is set in IRP$W_STS 


3 If IRP$V_FUNC is clear; deallocates the system buffer used for the write 
operation; if IRP$V_FUNC is set, the special kernel-mode AST copies the 
data to the user’s buffer and then deallocates the buffer in addition to 
performing other kernel-mode AST functions 


The special kernel-mode AST performs the following steps to complete a 
buffered read operation: 


1 Obtains the address of the system buffer from IRP$L_SVAPTE. 
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2 Obtains the number of bytes to write to the user’s buffer from IRP$L— 


BCNT. 


3 Obtains the address of the user’s buffer from the second longword of the 


system buffer header. 


4 Checks for write accessibility on all pages of the user’s buffer. 


5 Copies the data from the system buffer to the process’ buffer. 


6 Deallocates the system buffer. Note that the system uses the size listed in 
the buffer’s header to deallocate the buffer. 





7.5 FDT Routines Provided by VMS 


The VMS FDT routines perform I/O request validation that is common 

to many devices. Whenever possible, drivers should take advantage of 
these routines. Normally, if a VMS FDT routine is called, no additional 
FDT processing is required. All of the VMS FDT routines listed in 

Table 7-2 exit by transferring control to EXE$}QIODRVPKT, EXE$FINISHIO, 
EXE$FINISHIOC, or EXE$ABORTIO. Once a VMS FDT routine is called, no 


subsequent FDT processing occurs. 


For additional information about VMS FDT routines, see the pertinent routine 


descriptions in Appendix C. 


Table 7—2 FDT Routines Provided by VMS 


FDT Routine 
EXESONEPARM 


EXE$READ 


EXE$SENSEMODE 


EXE$SETCHAR' 


EXESSETMODE' 


Function 


Processes a nontransfer I/O function 
code that has one parameter 
associated with it 


Processes a logical-read or physical- 
read function for a direct 1/O 
operation 


Processes the sense-device-mode 
and sense-device-characteristics 
functions by reading fields of the 
UCB 


Processes the set-device-mode and 
set-device-characteristics functions 


Processes the set-device-mode and 
set-device-characteristics functions 
by creating a driver fork process 


Exit Method 
Transfers control to EXES$QIODRVPKT 


Aborts the |/O request if an error occurs, 
or dismisses and resubmits the |/O request 
if the user I/O buffers cannot be locked in 
memory; otherwise, transfers control to 
EXESOQIODRVPKT 


Transfers control to EXE$FINISHIO 


Transfers control to EXE$FINISHIO 


Aborts the I/O request if an error 
occurs; otherwise, transfers control to 
EXE$QIODRVPKT 


'Ilf setting device characteristics requires no device activity or requires no synchronization with fork processing, the 
driver's FDT entry can specify EXESSETCHAR; otherwise, it must specify EXESSETMODE. 
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Table 7-2 (Cont.) FDT Routines Provided by VMS 


FDT Routine Function 


EXESWRITE Processes a logical-write or 
physical-write function for a direct 
1/O operation 


EXESZEROPARM  ~ Processes a nontransfer !/O function 
code that has no associated 
parameters 


Exit Method 


Aborts the |1/O request if an error occurs, 
or dismisses the !/O request if the 

user |/O buffers cannot be locked in 
memory; otherwise, transfers control to 
EXESQIODRVPKT 


Transfers control to EXES$QIODRVPKT 


8 Writing a Start-I/O Routine 


A driver start-I/O routine activates a device and then waits for a device 
interrupt or timeout. This chapter describes the start-I/O routine. Chapter 10 
describes the reactivation of the driver routine that performs device- 
dependent I/O postprocessing. With a few exceptions, the start-I/O routine 
discussed in the following sections describes a DMA transfer using a single- 
unit controller. 





8.1 Transferring Control to the Start-1/O Routine 


The start-I/O routine of a device driver gains control from either of two VMS 
routines: EXES$QIODRVPKT or IOC6REQCOM. 


When FDT processing is complete for an I/O request, the FDT routine 
transfers control to EXESQIODRVPKT. If the designated device is idle, 
IOC$INITIATE is called to create a driver fork process. (This procedure 

is detailed in Section 7.2.1.2.) The driver fork process then gains control 

in the start-I/O routine of the appropriate driver. If the device is busy, 
EXE$QIODRVPKT calls EXE$INSIOQ, which queues the packet to the device 
unit’s pending-I/O queue. 


After a device completes an I/O operation, the driver fork process exits by 
transferring control to IOC6REQCOM. IOC$REQCOM inserts the IRP for the 
finished transfer into the postprocessing queue. It then dequeues the next IRP 
from the device unit’s pending-I/O queue and calls IOC$INITIATE to initiate 
the processing of this I/O request in the driver’s fork process at the entry 
point of the driver’s start-I/O routine. 





8.2 Context of a Driver Fork Process 


A start-I/O routine does not run in the context of a user process. Rather, it 
has the following context: 


System context Driver code can only refer to system virtual addresses. 


Kernel mode Execution occurs in the most privileged access mode and 
can, therefore, change IPL and obtain spin locks. 


High IPL The VMS routine that creates a driver fork process 
obtains the driver's fork lock, raising IPL to driver fork 
level before activating the driver. 


Kernel or Execution occurs on the kernel or interrupt stack. 

interrupt stack The driver must not alter the state of the stack 
without restoring the stack to its previous state before 
relinquishing control. The stack used depends on whether 
the 1/O startup is the result of a new !/O request or 
because a previously requested |/O operation has been 
completed. The choice of stacks must not affect the 
operation of the start-I/O routine. 
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8.2 Context of a Driver Fork Process 


In addition to the context described, the VMS packet-queuing routines set up 
R3 and R5 for a driver start-I/O routine, as follows: 


e =R3 contains the address of the IRP. 
e 5 contains the address of the UCB for the device. 


The start-I/O routine must preserve all general registers except RO, R1, R2, 
and R4. 


Before the packet-queuing routines call the start-I/O routine, they copy the 
following IRP fields into their corresponding slots in the device’s UCB: 


e IRP$L_BCNT (low-order word) — UCBSW_BCNT 
e IRP$W_BOFF — UCB$W_BOFF 
e IRP$L_SVAPTE — UCB$L_SVAPTE 





8.3 Functions of a Start-I/O Routine 
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The processing performed by a start-I/O routine is device specific. A start- 
I/O routine normally contains elements that perform the following functions 
to activate: 


e Analyzing the I/O function 
e Transferring the details of a request from the IRP into the UCB 
e¢ Obtaining and initializing the controller 


¢ Modifying device registers to activate the device 


A start-I/O routine of a DMA device driver performs additional tasks to 
prepare the device for a DMA transfer prior to activating the device. These 
tasks include the following: 


¢ Obtaining I/O adapter resources such as map registers and a buffered 
data path 


¢ Computing the starting address of a data transfer 


The following sections describe the general activities of a start-I/O routine for 
a typical device. The details of DMA processing are specific to the particular 
device. Section 12.2 describes the UNIBUS- and Q22 bus-related details of 
DMA transfers. Section 13.5.3 relates those tasks that MASSBUS DMA device 
drivers must perform. Section 14.5 discusses similar functions that drivers for 
generic VAXBI devices may need to perform. 
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8.3.1 Obtaining Controller Access 


If the device is one of several attached to a controller, the start-I/O routine 
invokes the VMS macro REQPCHAN to assign the controller’s data channel 
to the device unit. Controllers that control only one device do not require 
arbitration for the controller’s data channel. REQPCHAN calls the VMS 
routine JOC6REQPCHANL that acquires ownership of the controller data 
channel. 


The transfer being controlled by the start-I/O routine discussed here requires 
no seek preceding the transfer. Disk I/O is an example of a transfer that 
requires a seek first. To permit seeks to be overlapped with transfers, invoke 
REQPCHAN with the argument pri=HIGH. Specifying pri=HIGH inserts a 
request for a channel at the head of the channel wait queue. . 


If the channel is not available, IOC6REQPCHANL suspends driver processing 
by saving the driver’s context in the UCB fork block and inserting the fork 
block in the channel wait queue. IOCS6REQPCHANL then returns control to 
the caller of the driver, that is, to EXES$INSIOQ, as illustrated in Figure 8-1. 
This procedure is further discussed in Section 3.4.1. 


Figure 8—1_ Inserting a UCB into the Channel Wait Queue 
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The UCB fork block now represents the entire context of the suspended 
driver: 


e¢ Saved R3 containing the IRP address 

¢ Implicitly saved R5 containing the UCB address 

e A return address in the driver 

Note that, because IOC$RELCHAN moves the address of the device’s CSR 


into R4 before resuming a suspended driver, IOC6REQPCHANL does not 
save R4 in the UCB fork block. 
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If the channel is available, IOCSREQPCHANL locates the interrupt dispatch 
block (IDB) for the channel with a pointer in the UCB: 


UCB — CRB — IDB 


The IDB contains the address of the control and status register (CSR) for the 
channel (IDB$L_CSR). IOC6REQPCHANL returns the CSR address in R4. 
The driver for a unit attached to a dedicated controller must contain the code 
needed to load the CSR address into R4. 


IOC$REQPCHANL also writes the address of the new channel-owner’s UCB 
in the owner field of the IDB (IDB$L_OWNER). The driver’s interrupt service 
routine later reads this IDB field to determine which device unit owns the 
controller’s data channel. A driver for a single-unit controller must fill the 
IDB$L_OWNER field in its controller or unit initialization routines. 


The driver must maintain the stack in a known and consistent state for the 
resource-wait-queue mechanism to work. When IOC6REQPCHANL gains 
control, the top two items on the stack must be two return addresses: 


e 00(SP)—Address of the next instruction to be executed in the driver fork 
process. The transfer of control to IOC6REQPCHANL places this address 
on the stack. . 


e 04(SP)—Address of the next instruction to be executed in the routine that 
called the driver start-I/O routine. 


8.3.2 Obtaining and Converting the I/O Function Code and Its Modifiers 


The start-I/O routine extracts the I/O function code and function modifiers 
from the field IRPS-W_FUNC and translates them into device-specific function 
codes, which it loads into the device’s CSR or other control registers. The 
start-I/O routine creates and modifies a bit mask that is to be loaded into 
the CSR when the driver starts the device. To accomplish this, the start- 
I/O routine converts the function modifiers contained in IRPS6W_FUNC into 
device-specific bit settings in the general register. 


At this point, a UNIBUS/Q22 bus DMA driver follows procedures to obtain 
I/O bus resources and compute the size and starting address of a transfer. 
These procedures are discussed in Section 12.2. MASSBUS DMA device 
drivers perform the steps indicated in Section 13.5.3. 


8.3.3 Preparing the Device Activation Bit Mask 


For a typical device, the start-I/O routine prepares the device-activation bit 
mask by setting the interrupt-enable bit and the go bit in the general purpose 
register that also contains the high-order bits of the bus address and the 
device-function bits. At this point, the general register contains a complete 
command for starting the transfer, also known as the control mask. 


When the start-I/O routine copies the contents of the register into the device’s 
CSR, the device starts the transfer. Before activating the device, however, the 
start-I/O routine should perform the steps described in Sections 8.3.4 and 
8.3.5. 
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8.3.4 Synchronizing Access to the Device Database 


The start-I/O routine invokes the VMS macro DEVICELOCK to synchronize 
its access to device registers with the interrupt service routine. This macro 
invocation is doubly important, for it establishes the context wherein the 
driver can later issue the wait-for-interrupt macro (WFIKPCH or WFIRLCH). 
The wait-for-interrupt macros expect the driver’s fork IPL to be on the stack, 
as placed there by the DEVICELOCK macro. In addition, the wait-for- 
interrupt macros issue the DEVICEUNLOCK macro to release ownership of 
the device lock and restore the previous IPL. 


8.3.5 Checking for a Local Processor Power Failure 


After synchronizing access to device registers, the start-1/O routine invokes 
the VMS macro SETIPL to raise IPL to IPL$_POWER to block all interrupts 
on the local processor. 


The start-I/O routine then examines the powerfail bit in the UCB’s status 
longword (UCB$V_POWER in UCB$L_STS) to determine whether a local 
power failure has occurred since the start-I/O routine gained control. If the 
bit is not set, the transfer can proceed. 


If the bit is set, a power failure might have occurred between the time that the 
start-I/O routine wrote the first device register and the time that the start-I/O 
routine is ready to activate the device. Such a power failure could modify the 
already-written device registers and cause unpredictable device behavior if 
the device were to be started. 


If the bit UCB$V_POWER is set, the start-I/O routine branches to an error 
handler in the driver. The driver error handler must perform the following 
actions: 


¢ Clear UCB$V_POWER 


e Issue the DEVICEUNLOCK macro to release the device lock and restore 
IPL to fork IPL 


After performing these tasks, many drivers transfer control to the beginning 
of the start-I/O routine, which restarts the processing of the I/O request. 


8.3.6 Activating the Device 


If no power failure has occurred, the start-I/O routine copies the contents 
of the control mask into the device’s CSR. When the device notices the new 
contents of the device register, it begins to transfer the requested data. 
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8.4 Waiting for an Interrupt or Timeout 


Once the start-I/O routine activates the device, the driver fork process cannot 
proceed until one of these events occurs: 


e The device generates a hardware interrupt. 


e The device does not generate a hardware interrupt within an expected 
time limit, which is to say that a device timeout occurs. 


Still executing at IPL$_POWER, the driver’s start-I/O routine asks VMS to 
suspend the driver fork process by invoking one of the following macros: 


WFIKPCH Wait for an interrupt or timeout and keep the controller data 
channel . 

WFIRLCH ~ Wait for an interrupt or timeout and release the controller data 
channel 


The WFIKPCH and WFIRLCH macros require the address of a timeout 
handling routine in the excpt argument. Optionally, but almost always, the 
driver can also indicate the number of seconds the system must wait before 
signaling a timeout in the time argument. A full description of these macros 
appears in Appendix C. 


Both macros invoke routines that release ownership of the device lock, 
relinquish synchronization, and return IPL to the previous level when exiting. 
These routines expect to find the return IPL on the stack. This IPL is saved 
on the stack by the DEVICELOCK macro as described in Section 8.3.4. 


Drivers generally keep the controller data channel while waiting for the 
interrupt or timeout. Drivers of devices with dedicated controllers always 
keep the channel because only one unit ever needs it. For devices that share 
a controller, some operations, such as disk seeks, do not require the controller 
once the operation has begun. In such cases, the driver can release the 
controller’s data channel while waiting for an interrupt or timeout so that 
other units on the controller can start their operations. 


8.4.1. Expansion of WFIKPCH Macro 


Because the WFIKPCH and WFIRLCH macros are similar, the description that 
follows analyzes the expansion of WFIKPCH only. 


If the driver specifies the time argument in the macro call, the macro pushes 
the value of the argument into the stack. If the time argument is not 
specified, the macro pushes the value 65,536 onto the stack. IOC$WFIKPCH 
uses the time value to calculate the length of time VMS waits before 
transferring control to a device timeout handler. 


WFIKPCH completes its expansion with two lines of code: 


JSB G* IOC$WF IKPCH 
.WORD EXCPT-. 


The execution of the JSB instruction pushes the address following the JSB 
onto the stack as the address to which the called routine would normally 
return with an RSB instruction. 
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8.4.2 IOC$SWFIKPCH Routine 


The VMS routine IOC$WFIKPCH, invoked by the macro WFIKPCH, performs 
the functions necessary for the driver fork process to wait for a device 
interrupt or timeout. IOC$WFIKPCH first adds 2 to the address on the top 
of the stack so that the top of the stack contains the address of the next 
instruction in the driver after the macro invocation. This address is where 
the driver resumes execution as a result of an interrupt service routine’s JSB 
instruction. 


IOC$WFIKPCH then saves the contents of R3, R4, and the address to which 
control must be returned to the driver, which it takes from the top of the 
stack. It saves this information in the first part of the UCB in the UCB fork 
block. 


Note that, after an interrupt, the interrupt service routine must restore R5 so 
that it contains the address of the UCB. The interrupt service routine normally 
obtains the address of the UCB from the field IDB$L_OWNER of the IDB. 


The VMS routine that detects a device timeout calculates the address of the 
driver’s timeout routine by subtracting 2 from the saved PC in the UCB’s fork 
block and calling indirectly through the result. For example: 


MOVL UCB$L_FPC(R5) ,R2 ; Get saved PC 

CVTWL -(R2),-(SP) ; Get offset to timeout 
; handler 

ADDL (SP)+,R2 ; Add to relative driver 


; address to obtain relative 
; handler address 
JSB (R2) ; Call timeout handler 


IOC$WFIKPCH sets bits in the UCB (UCB$V_INT and UCB$V_TIM in 
UCB$L_STS) to indicate that interrupts and timeouts are expected from the 
device. IOCSWFIKPCH also writes the device timeout absolute time in the 
field UCB$L_DUETIM. The absolute time is the number of seconds since the 
operating system was bootstrapped plus the number of seconds specified in 
the time argument to the macro. 


Finally, IOC$WFIKPCH reenables interrupts by releasing the device lock 
and lowering IPL to fork level, the IPL at which the driver was executing 
previously. It then returns control to the caller of the driver. 


Q Writing an Interrupt Service Routine 


When a device generates a hardware interrupt, it requests an interrupt at the 
appropriate device IPL. Either the device or its adapter requests a processor 
interrupt at that IPL. When the processor executes at an IPL below that device 
IPL, interrupt dispatching begins. 


The mechanism of interrupt dispatching has no direct bearing on the contents 
of a driver’s interrupt service routine. Its implementation varies slightly 
according to the VAX processing system and I/O subsystem in use. To obtain 
background information on the dispatcher, refer to the overview provided 

in Section 12.3, which also details the method of dispatching UNIBUS/Q22 
bus device interrupts. MASSBUS device driver writers should refer also to 
Section 13.4; generic VAXBI device driver writers should read the discussion 
in Section 14.3.1. 


For most device drivers, the driver prologue table contains, in the 
reinitialization section established by the DPT_STORE macro, the address 

of one or more interrupt service routines. Each interrupt service routine 
corresponds to an interrupt vector on the I/O bus. You specify the address of 
an I/O bus vector using the SYSGEN command CONNECT, as described in 
Section 15.2.2. 


Most device interrupt service routines perform the following functions: 

e Locate the device’s UCB 

e Determine whether the interrupt was solicited 

e Reject or process unsolicited interrupts 

e Activate the suspended driver to process solicited interrupts 

Figure 9-1 illustrates the general flow of interrupt handling. The remaining 


sections of this chapter describe the handling of solicited and unsolicited 
interrupts in further detail. 
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Figure 9-1 Flow of Interrupt Servicing 
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9.1 Interrupt Context 


When the interrupt dispatcher calls a driver’s interrupt service routine, 
execution context is as follows: 


e RO through R5 are saved on the stack. 

e Only system address space may be accessed. 
e IPL is at hardware device interrupt level. 

e The processor is running in kernel mode. 


e The processor is running on the interrupt stack. 


The stack contains the following information: 


Stack Location Content 

OO(SP) Pointer to the address of the IDB 
04(SP) through 24(SP) Saved RO through R5 

28(SP) PC at the time of the interrupt 
32(SP) PSL at the time of the interrupt 


In the course of its processing, an interrupt service routine must remove the 
IDB pointer and the saved registers from the stack before dismissing the 
interrupt with an REI instruction. 





9.2 Servicing a Solicited Interrupt 


When a driver’s fork process activates a device and expects to service a 
device interrupt as a result, the fork process suspends its execution and waits 
for an interrupt to occur. The suspended driver is represented only by the 
contents of the fork block in the device’s UCB and the stack, which contain 
the following information: 


e A description of the I/O request and the state of the device 
e The contents of R3 and R4 

e The implicit contents of R5 (the address of the UCB fork block) 

e The address at which to return control to the driver 


e The implicit address of a timeout handling routine 


When the interrupt service routine returns control to the main line of driver 
_ processing, it has only restored the contents of R3, R4, R5, and the PC. 


A driver’s interrupt service routine performs the following tasks to process the 
interrupt and transfer control to the waiting driver: 


1 Obtains the address of the device’s UCB from the IDB, as follows: 
00(SP) — CRB — IDB — IDB$L_OWNER — UCB 
The interrupt service routine restores the UCB address to R5. 


2 Issues the DEVICELOCK macro to obtain synchronized access to device 
registers. 
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3 Tests the interrupt-expected bit in the UCB status longword (UCB$V_INT 
in UCB$L_STS). If the bit is set, the driver is waiting for an interrupt 
from this device. After performing this test, the interrupt service routine 
must clear UCB$V_INT to indicate that it has received the expected 
interrupt. 


Note: Because device timeout processing mostly occurs at fork IPL (see 
Section 10.2), a driver’s interrupt service routine, executing at device 
IPL, could interrupt the processing of a timeout on the same device 
unit. For this reason, the driver's interrupt service routine should 
check the interrupt-expected bit (UCB$V_INT) before handling the 
interrupt. VMS clears this bit before it calls the driver’s timeout 
handler. 


4 Obtains device-status or controller-status information from the device 
registers, if necessary, and stores the status information in the UCB. 


5 Places the contents of UCB$L_FR3 and UCB$L_FR4 in R3 and R4, 
respectively. 


6 Issues a JSB instruction to the waiting driver’s PC address, which is saved 
in the UCB fork block at UCB$L_—FPC. 


The restored driver should execute as briefly as possible in interrupt context. 
As soon as possible, the driver should invoke the IOFORK macro to request 
the creation of a fork process at the driver’s fork IPL. It must do this in 
order to complete the I/O operation. Forking lowers the IPL of driver 
execution below device IPL, allowing the processor to service additional 
device interrupts. IOFORK calls the routine EXE$IOFORK. EXES$IOFORK 
inserts into the appropriate fork queue the UCB fork block that describes the 
driver process. It then returns control to the driver’s interrupt service routine. 
(See Section 10.1.1 for additional information on driver forking.) 


The interrupt service routine then performs the following steps: 
1 Removes the IDB pointer from the stack 


2 Issues the DEVICEUNLOCK macro to release ownership of the device 
lock 


3 Restores RO through R5 


4 Dismisses the interrupt with an REI instruction 





9.3 Servicing an Unsolicited Interrupt 


A device requests an interrupt to indicate to a driver that the device has 
changed status. If a driver’s fork process starts an I/O operation on a device, 
the driver expects to receive an interrupt from the device when the I/O 
operation completes or an error occurs. 


Other changes in the device’s status occur when the device has not been 
activated by a device driver. The device reports such a change by requesting 
an unsolicited interrupt. For example, when a user types on a terminal, the 
terminal requests an interrupt that is handled by the terminal driver. If the 
terminal is not attached to a process, the terminal driver causes the login 
procedure to be invoked for the user at the terminal. 
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As another example, an unsolicited interrupt occurs whenever a disk drive 
goes offline, as could happen when an operator spins it down or pushes the 
offline button. The disk driver services the interrupt by altering volume and 
unit status bits in the disk device’s UCB. 


Devices request unsolicited interrupts because some external event has 
changed the status of the device. A device driver can handle these interrupts 
in two ways: 


¢ Ignore the interrupt as spurious 


e Examine the device registers and take action according to their indications 
of changed status, and then poll for any other changes in device status 


As mentioned in Section 9.2, an interrupt service routine first obtains the 
address of the device’s UCB from the IDB. It then issues the DEVICELOCK 
macro to obtain synchronized access to device registers. 


The routine determines whether an interrupt is solicited or not by examining 
the interrupt-expected bit in the UCB status longword (UCB$V_INT in 
UCB$L_STS). All UNIBUS, Q22 bus, and generic VAXBI device drivers must 
use this method to determine whether or not an interrupt is solicited; the 
address of the unsolicited interrupt service routine, specified in the driver 
dispatch table, is used only by MASSBUS drivers (see Sections 13.4 and 
13.6.) 


If the interrupt is unsolicited, the driver can reject the interrupt with the 
following code sequence: 


1 Remove the IDB pointer from the stack 
2 Restore RO through R5 


3 Dismiss the interrupt with an REI instruction 


If the driver decides to handle the unsolicited interrupt, it must observe 
certain precautions. Certain methods of servicing unsolicited interrupts—for 
instance sending a message to the operator or the job controller’s mailbox— 
must be accomplished at an IPL lower than device IPL. Although the interrupt 
service routine can legitimately fork to accommodate unsolicited mteHup ts, it 
should exercise extreme caution in doing so. 


If UCB$V_BSY is set in UCB$L_STS, the UCB fork block is currently in use 
by the driver's start-I/O routine. An attempt by the interrupt service routine 
to concurrently use the fork block can destroy the fork context already stored 
in that UCB. Moreover, if UCB$V_BSY is not set, the interrupt service routine 
cannot safely assume that the fork block is not in use, for it may be currently 
employed to service a previous unsolicited interrupt. 


To avoid confusion, code servicing an unsolicited interrupt must ensure that 
the fork block it requires is not being used. Perhaps the safest method to 
guarantee this is for the driver to define a separate fork block in a device- 
specific UCB extension. The driver should also define a semaphore bit to 
control access to this fork block and protect against multiple forking. Note 
that the driver should access the semaphore bit using interlocked instructions 
(for example, BBSSI or BBCC]). 
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If, upon servicing an unsolicited interrupt, the driver’s interrupt service 
routine examines the semaphore and discovers that a fork is already in 
progress (that is, the bit is set), it should not attempt to fork. 


The VMS routine that creates the fork process (once these conditions are 
satisfied) returns control to the interrupt service routine. The interrupt service 
routine then releases the device lock, restores the saved registers, and issues 
an REI instruction to dismiss the interrupt. 


9.3.1 Examples of Unsolicited Interrupts 


A card reader requests an unsolicited interrupt when a user puts the reader 
online. Once the card-reader driver’s interrupt service routine determines 
that the interrupt is unsolicited, the routine analyzes the interrupt, as in the 
following code example. 


Because only one sequence of instructions can use the UCB as a fork block, 
the interrupt service routine performs the following steps before it creates the 
fork process: 


e Ensures that no one is using the device, and that no one wants to use it, 
by determining that the reference count (UCB$W_REFC) is zero. 


e Ensures that it is not already using the UCB, to create a fork process in 
order to lower IPL and to send a message to the job controller, by testing 
the job-attached bit (UCB$V_JOB in UCB$W_DEVSTS). 


CRSINT: : 
MOVL  @(SP)+,R3 ;Get address of IDBO 
MOVQ IDB$L_CSR(R3) ,R4 ‘Get controller CSR and owner UCB address@ 
DEVICELOCK LOCKADDR=UCB$L_DLCK (R5) ,- 
PRESERVE=NO, - 
CONDITION=NOSETIPL ;Obtain device lock® 
BBCC #UCB$V_INT, UCB$L_STS(R5) ,10$ ;If clear, interrupt not expected@ 


’ 


; UNSOLICITED INTERRUPT 


10$: MOVZWL CR_CSR(R4) ,RO ;Get reader status 
MOVZBW #CR_CSR_M_IE,CR_CSR(R4) ;Clear status, enable interrupts@ 
BITW #CR_CSR_M_ONLINE, RO ;Reader transition to online?@ 
BEQL 20$ ;If equal no 
TSTW UCB$W_REFC (R5) ;Device assigned or allocated?@ 
BNEQ 20$ ;If not equal yes 
BBSS #UCB$V_ JOB, UCB$W_DEVSTS (R5) , - 
20$ ;If set, message already sentO 
BSBB 30$ ;Send message to job controller 
20$: DEVICEUNLOCK LOCKADDR=UCB$L_DLCK (R5) , - 
PRESERVE=NO0 ;Release device lock 
MOVQ (SP)+,RO ;Restore registers 


MOVQ (SP)+,R2 
MOVQ (SP)+,R4 
REI 
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30$: FORK ;Create fork processO 
MOVZBL #MSG$_CRUNSOLIC,R4 ;Set message type 
MOVL G*SYS$AR_JOBCTLMB , R3 ;Set address of job controller mailbox 
JSB G°EXE$SNDEVMSG ;Sent message to job controller 


BLBS RO, 40$ 


40$: RSB 
0 


,2) 


-If LBS successful notification® 


BICW #UCB$M_JOB ,UCB$W_DEVSTS(R5) ;Clear message sent pit® 


The interrupt service routine obtains the address of the IDB from the top 
of the stack. 


By means of this action, it obtains the address of the control and status 
register (CSR) in R4 and restores the address of the UCB in R5.! 


It issues a DEVICELOCK macro to secure synchronized access to device 
registers and UCB fields. 


It checks for an unsolicited interrupt by testing the interrupt expected bit 
in the UCB status longword. 


Because the interrupt is unsolicited, the routine clears all CSR bits except 
for the interrupt-expected bit. 


It confirms that the reader was just placed on line by examining a saved 
copy of the CSR. 


It examines the reference count field of the device’s UCB (UCB$W_REFC) 
to determine whether a process has allocated the device or assigned a 
channel to it. 


If the reference count is zero, the interrupt service routine tests the 
job-attached bit in the device-dependent status field (UCB$V_JOB in 
UCB$W_DEVSTS) to make sure it has not already sent the job controller 
a message about the card reader being placed on line. 


If the job-attached bit is not set, the routine sets the bit and creates a fork 
process to send the message to the job controller, using the system routine 
EXE$SNDEVMSG (described in Appendix C). It is necessary to lower IPL 
from device IPL by forking at this point because EXESSNDEVMSG 
expects its caller’s IPL to be no greater than IPL$_MAILBOX. 


When the interrupt service routine regains control, it releases the device lock, 
restores RO through R5 and dismisses the interrupt with an REI instruction. 
(The interrupt service routine removed the IDB pointer from the stack earlier 
in its execution in order to obtain CSR and UCB addresses.) 


© 


@ 


When the fork process created at step 8 eventually executes, it writes a 
message to the job controller’s mailbox, indicating that the card reader is 
on line. 


If the fork process successfully sends the message, it leaves the job- 
attached bit set to prevent the job controller from receiving any further 
messages about the card reader’s state. (The driver’s cancel-I/O routine 
later clears the bit.) 


‘ Because the card reader has a dedicated controller, the IDB$L__OWNER field always points to the UCB for the 


single unit: 


00(SP) + CRB — IDB — IDB$L_OWNER — UCB 
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@® If the send-message request fails, the fork process clears the job-attached 
bit so that if the card reader makes a subsequent state change to on line, 
the interrupt service routine can attempt again to send a message to the 
job controller. 


Another example of unsolicited interrupt processing occurs in a device driver 
for a multiunit controller. When a disk is placed off line, the disk drive 
hardware requests an interrupt. The driver interrupt service routine must 
determine what device unit requested the interrupt, obtain status information 
from the disk device’s CSR, and then decide whether the interrupt was 
solicited. 


Because it must access device UCB fields and device registers, the interrupt 
service routine first obtains the appropriate device lock. If the interrupt is 
unexpected, it calls code that services the unsolicited interrupt. This code 
checks the status of the volume, as described in the following steps: 


1 It sets a bit in the UCB to indicate that the unit is on line (UCB$V_ 
ONLINE in UCB$L_STS). 


2 If the UCB’s volume-valid bit is set (UCB$V_VALID in UCB$L_STS), the 
routine tests the volume valid status bit in a device register to determine 
whether the volume status has changed. If the volume is no longer valid, 
the routine clears the UCB volume valid bit. 


3 The routine returns control to the driver’s interrupt service routine. 


The driver’s interrupt service routine then polls the other device units on the 
controller to determine whether any other units requested interrupts while the 
first interrupt was being processed. When no unit requires interrupt servicing, 
the routine removes the IDB pointer from the stack, releases the device lock, 
restores registers RO through R5, and dismisses the interrupt with an REI 
instruction. 


10 Completing an I/O Request and Handling Timeouts | 


Once a driver has activated the device and invoked the wait-for-interrupt 
macro, the driver remains suspended until the device requests an interrupt or 
times out. 


If the device requests an interrupt, the driver’s interrupt service routine 
handles the interrupt and then reactivates the driver at the instruction 

following the wait-for-interrupt macro. The reactivated driver performs 
device-dependent I/O postprocessing. 


If the device does not request an interrupt within the designated time interval, 
the system transfers control to the driver’s timeout handling routine. The 
address of the timeout handling routine is specified as the excpt argument to 
the wait-for-interrupt macro. 





10.1 1/O Postprocessing 


10.1.1 EXESIOFORK 


Once the driver interrupt service routine has processed an interrupt, it 
transfers control to the driver by issuing a JSB instruction. At this point, 

the driver is executing in interrupt context. If the driver were to continue 
executing in interrupt context, it would lock out most other processing on the 
processor including the handling of hardware interrupts. 


To restore the driver to the context of a driver fork process, the driver 
invokes the VMS macro IOFORK. Once the fork process has been created 
and dispatched for execution, it executes the driver code that completes the 
processing of the I/O request. 


IOFORK generates a call to the routine EXE$IOFORK. EXE$IOFORK converts 
the driver context from that of an interrupt service routine to that of a fork 
process by performing the following steps: 


1 It disables software timeouts by clearing the timeout enable bit in the 
UCB status longword (UCB$V_TIM in UCB$L_STS). 


2. It saves R3 and R4 of the current driver context in the UCB fork block 
(UCB$L_FR3 and UCB$L_FR&4). 


3 It saves the current driver PC in the UCB fork block (UCB$L_FPC). 
(The driver PC is the top longword on the stack, as a result of the JSB to 
EXE$IOFORK.) 


4 It obtains the fork lock index of the driver from the UCB (UCB$B_FLCK) 
and uses it to determine in which fork queue it should place the fork 
block. | 


5 It inserts the address of the UCB fork block (R5) into the processor-specific 
fork queue corresponding to the driver’s fork IPL. 
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6 Finally, if the fork block is the first entry in the fork queue, EXE$IOFORK 
requests a software interrupt from the local processor at the driver’s fork 
IPL. 


The steps listed previously move the fork process’s context into the UCB’s 
fork block. They save R3 through R5 and the driver’s PC address. The 
driver’s fork process resumes processing when the VMS fork dispatcher 
dequeues the UCB fork block from the fork queue, and reactivates the driver 
at the driver’s fork IPL. 


10.1.2 Completing an I/O Request 
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When VMS reactivates a driver’s fork process by dequeuing the fork block, 
the driver resumes processing of the I/O operation holding the appropriate 
fork lock at fork IPL. Generic VAXBI devices perform whatever device- 
dependent operations are needed to prepare an I/O request for completion. If 
the device has completed the I/O operation without errors, a UNIBUS/Q22 
bus driver for a DMA device proceeds as follows: 


1 Purges the data path 


2 Releases the buffered data path (applies only to UNIBUS DMA device 
drivers) 


3 Releases map registers (does not apply to MicroVAX I DMA device 
drivers) 


4 Releases the controller (applies only to drivers of devices on multiunit 
controllers) 


5 Checks device register images saved in the UCB to determine the status 
of the I/O operation 


6 Saves in the IRP the status code, transfer count, and device-dependent 
status that is to be returned to the user process in an I/O status block 


7 Returns control to the operating system 


The first three steps listed previously apply to UNIBUS/Q22 bus DMA 
transfers only and are discussed in Section 12.2. The following sections 
describe the last three steps. 


Releasing the Controller 

To release the controller channel, the driver code invokes the VMS macro 
RELCHAN. RELCHAN calls the VMS routine IOC$RELCHAN. If another 
driver is waiting for the controller channel, IOC$6RELCHAN grants that 
driver’s fork process the channel, restores its context from the UCB fork 
block, and transfers control to the saved PC. When no more drivers are 
awaiting the channel, IOC$RELCHAN returns control to the fork process that 
released the channel. 


Drivers for devices with dedicated controllers need not release the controller’s 
data channel (as discussed in Sections 8.3.1 and 11.1). By means of code in 
the unit initialization routine, these drivers set up the device’ s UCB so that 
the device owns the controller permanently. 


Drivers must be executing at driver’s fork IPL when they invoke RELCHAN 
or call IOC6RELCHAN. 
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10.1.2.2 Saving Status, Count, and Device-Dependent Status 
To save the status code, transfer count, and device-dependent status, the 
driver performs the following steps: 


1 Loads a success status code (SS$_NORMAL), or whatever is appropriate, 
into bits 0 through 15 of RO. 


2 Loads the number of bytes transferred into the high-order 16 bits of RO 
(bits 16 through 31), if the I/O operation performed by the device is a 
transfer function. 


3 Loads device-dependent status information, if any, into R1.! 


10.1.2.3 Returning Control to the Operating System 
Finally, the driver fork process returns control to the system by invoking 
the REQCOM macro to complete the I/O request. REQCOM issues a JMP 
instruction to the VMS routine IOC$6REQCOM. IOC$REQCOM locates the 
address of the I/O request packet (IRP) corresponding to the I/O operation 
in the device’s UCB (UCB$L_IRP). It then writes the two longwords of 
completion status contained in RO and R1 into the media field of the IRP 
(IRP$L_MEDIA and IRP$L_—MEDIA+4). 


IOC$REQCOM then inserts the IRP in the local processor’s I/O- 
postprocessing queue and requests a software interrupt at IPL$_IOPOST 


from the local processor so the postprocessing begins when IPL drops below 
IPL$_IOPOST. 


If the error-logging bit is set in the device’s UCB (UCB$V_ERLOGIP in 
UCB$L_STS), IOC$REQCOM obtains the address of the error message buffer 
from the UCB (UCB$L_EMB). It then writes the following information into 
the error buffer: 


e Final device status (UCB$W_DEVSTS) 
e Final error count (UCB$B_ERTCNT) 
¢ Maximum error retry count for the driver 


e Two longwords of completion status (RO and R1) 


To release the error message buffer, IOC6REQCOM calls ERLGRELEASEMB. 
Section 11.3 describes error logging in more detail. 


If any IRPs are waiting for driver processing, IOC6REQCOM dequeues an IRP 
from the head of the queue of packets waiting for the device unit (UCB$L_— 
IOQFL), and transfers control to IOC$INITIATE. IOC$INITIATE initiates 
execution of this I/O request in the driver’s fork process, by activating the 
driver’s start-I/O routine, as described in Section 4.2.1. 


Otherwise, IOC$REQCOM clears the unit-busy bit in the device’s UCB 
status longword (UCB$V_BSY in UCB$L_STS) and transfers control to 
IOC$RELCHAN to release the controller channel in case the driver failed to 
do so. IOC$RELCHAN, in turn, returns control to the caller of the driver fork 
process (if the fork process issued the REQCOM macro). This is generally 
the VMS fork dispatcher. The fork dispatcher releases the fork lock, restores 
saved registers, and dismisses the fork IPL software interrupt with an REI 
instruction. 


' RO and R1 are the status values that VMS returns to the user process in the I/O status block specified in the 
original $QIO system service. 
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The remaining steps in processing the I/O request are performed by VMS 
I/O postprocessing. (See Section 4.3.1 for additional information.) 





Timeout Handling Routines 


VMS transfers control to the driver’s timeout handling routine if a device unit 
does not request an interrupt within the time limit specified in the invocation 
of the wait-for-interrupt macro. Among its other activities, the VMS software 
timer interrupt service routine, having raised IPL from IPL$¢_TIMERFORK to 

IPL$_SYNCH, scans UCBs once every second to determine whether a device 
has timed out. 


When the software timer interrupt service routine locates a device that 
has timed out, the routine calls the driver’s timeout handling routine by 
performing the following steps: 


1 It obtains both the fork lock and the device lock associated with the 
device unit to synchronize access to its fork database and device database. 
It raises IPL to device IPL as a result of obtaining the device lock. 


2 It raises IPL on the local processor to IPL$_POWER to block local power 
failure servicing. 


3 It disables expected interrupts and timeouts on the device by clearing bits 
in the status field of the device’s UCB (UCB$V_INT and UCB$V_TIM in 
UCB$L_STS). 


4 It sets the device-timeout bit in the UCB status field (UCB$V_TIMOUT in 
UCB$L_STS). 


5 It lowers IPL to hardware device interrupt IPL (UCB$B_DIPL). 


6 It restores the saved R3 and R4 of the driver’s fork process from the UCB 
fork block (UCB$L_FR3 and UCB$L—FR&4). 


7 ‘It restores R5 (address of the UCB fork block). 


8 It computes the address of the driver’s timeout handling routine from the 
saved PC in the UCB fork block (UCB$L—_FPC). 


9 It transfers control to the driver’s timeout handling routine. 


The driver’s timeout handling routine executes in the following context: 
e¢ RO through R5 are saved on the stack. 

e R5 contains the address of the UCB for the device that timed out. 

e¢ Only system address space may be accessed. 

e The processor is running in kernel mode. 

¢ The processor is running on the interrupt stack. 

¢ The processor holds both fork lock and device lock. 


e IPL is at hardware device interrupt level. 
A timeout handling routine returns control to the software timer interrupt 
service routine by issuing an RSB instruction. The driver’s fork process 


eventually regains control, with R3 and R4 restored from UCB$L_FR3 and 
UCB$L_FR4. 
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Certain timeout handling routines may find it useful to fork to execute low 
priority code or to accomplish certain tasks, such as the restarting of an I/O 
request (see Section 10.2.1). If a driver uses this method, its interrupt service 
routine should check the interrupt-expected bit (UCB$V_INT) before handling 
the interrupt. The operating system clears this bit before it calls the driver’s 
timeout handling routine. This allows the routine to determine whether 
device-timeout processing is in progress at fork IPL. 


During recovery from a power failure, VMS forces a device timeout by 
altering the timeout field (UCB$L_DUETIM) of a UCB if that device’s UCB 
records that the unit is waiting for an interrupt or timeout (UCB$V_INT and 
UCB$V_TIM set in UCB$L_STS). The timeout handling routine can perceive 
that recovery from a power failure is occurring by examining the power bit 
(UCB$V_POWER in UCB$L_STS) in the UCB. 


A timeout handling routine usually performs one of three functions: 
e It retries the I/O operation unless a retry count is exhausted. 


e It aborts the I/O request, returning status (for instance, SS$_TIMEOUT) 
in RO. 


e It sends a message to an operator mailbox and waits for a subsequent 
interrupt or timeout. 


10.2.1 Retrying an I/O Operation 


Some devices might retry an I/O operation after a timeout. For example, a 
disk driver’s timeout handling routine might take the following steps after a 
transfer timeout: 


1 Invokes the FORK macro to lower IPL to fork level. 

2 Releases any owned map registers, data path, and controller data channel. 
3 Determines whether it is possible to retry the I/O operation. 
4 


Examines the error retry count (UCB$B_ERTCNT) to determine whether 
it is possible to retry the I/O operation. 


If the retry count is exhausted, the timeout handling routine sets the error 
code, performs a normal abort I/O cleanup operation, and issues the 
REQCOM macro to complete the I/O request. 


If the retry count is not exhausted, the routine proceeds to the next step. 


5 Examines the power bit (UCB$V_POWER in UCB$L_STS) to determine 
if it must take special steps before retrying the operation. For instance, 
the timeout handling routine should load the address of the IRP into R3 
and reload the following fields of the IRP into the corresponding UCB 
fields, if they have been altered by partial processing of the I/O request: 


IRP$L_BCNT 
IRP$W_BOFF 
IRP$L_SVAPTE 


These actions set up an environment in which the transfer can be retried 
from the beginning. 


6 Calls ERL6DEVICTMO to log the device timeout if the driver supports 
error logging (see Section 6.2). 
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7 Decreases the error retry count (UCB$B_ERTCNT). 
8 Clears the UCB timeout bit (UCB$V_TIMOUT) in UCB$L_STS. 


9 Branches to the start-I/O routine to retry the operation. 


10.2.2 Aborting an I/O Request 


A driver’s timeout handling routine aborts the I/O request when it exhausts 
its retry count or when, having read device registers, the driver determines 
that some fatal error condition has occurred such that there is no point in 
retrying the request. Similarly, the routine aborts a request if the device’s 
cancel-I/O bit (UCB$V_CANCEL in UCB$L_STS) is set, signifying that a 
cancel-I/O request was made. 


To abort an I/O request, a timeout handling routine performs the following 
sequence of steps: 


1 Clears the device control and status register (CSR), if appropriate to the 
device and controller 


Invokes the FORK macro to lower IPL to fork level 

Releases any owned map registers, data path, and controller data channel 
Loads the abort status code (SS$_ABORT) into the low word of RO 
Clears bits 16 through 31 in RO to indicate that no data was transferred 


ao a fF WwW N 


Issues the REQCOM macro to complete the request 


10.2.3 Sending a Message to the Operator 
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The following sequence describes a timeout handling routine that sends a 
message to the operator’s mailbox and then goes back into a wait-for-interrupt 
or timeout state on the presumption that subsequent human intervention will 
make the device operational: 


1 The timeout handling routine invokes the FORK macro to lower IPL to 
driver fork level. 


2 It checks the cancel-I/O bit in the UCB status longword (UCB$V_ 
CANCEL in UCB$L_STS). 


If UCB$V_CANCEL is set, the timeout handling routine can abort the 
request. However, if UCB$V_CANCEL is clear, the timeout handling 
routine performs the following actions: 


a. Saves R3 and R4 on the stack. 


b. Loads an OPCOM message code, such as MSG$_DEVOFFLIN, into 
R4. Note that the driver must invoke the message definition macro 
$MSGDEF (located in SYS$LIBRARY:STARLET.MLB) to use these 
message codes. 


c. Loads the address of the operator’s mailbox (a pointer to which is 
located at SYS$AR_OPRMBX) into R3. 
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d. Calls a VMS routine to place the message in the operator’s mailbox, 
as follows: 


JSB G* EXE$SNDEVMSG 
e. Restores R3 and R4. 


Invokes the DEVICELOCK macro to raise IPL to device IPL and 
obtain the associated device lock. 


g. Issues a SETIPL macro to raise IPL$6_POWER and prevent power 
failure interrupts on the local processor. 


h. Invokes the WFIKPCH macro to wait for another interrupt or timeout. 


When the OPCOM process reads the message in its mailbox, it sends the 
requested message, in this case “device-offline,” to all operator terminals 
enabled for that device class. 
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11 > Other Driver Routines 


Drivers normally contain initialization, cancel-I/O, error logging, and register 
dumping routines. The driver prologue table specifies the addresses of the 
unit and controller initialization routines.! The driver dispatch table (DDT) 
contains the addresses of the cancel-I/O, error logging, and register dumping 
routines. The type of device determines which of these routines are required 
in a driver. 


Drivers more rarely require a driver unloading routine, cloned UCB routine, 
or unit delivery routine. VMS, however, provides a method for specifying 
these routines in the DPT or DDT. A brief discussion of the driver unloading - 
routine appears in Section 15.2.3. Section 11.4 describes the functions of a 
cloned UCB routine. A description of the unit delivery routine appears in 
Section 15.4.2. | 





11.1 Initialization Routines 


Most device controllers and device units require initialization both when 
the corresponding device driver is loaded and when the operating system 

is recovering from a power failure. At these times, the duty of initialization 
routines is to prepare controllers and device units for operation, according to 
their characteristics. 


The VMS operating system always calls controller and unit initialization 
routines with IPL raised to IPL$_POWER. The high IPL prevents any 
interrupts from reaching the local processor while initialization is occurring; 
for this reason, initialization routines should only contain code that is 
absolutely needed at initialization time. Initialization routines should not 
explicitly lower IPL. The system calls initialization routines with a JSB 
instruction; the routines return by executing an RSB instruction. 


11.1.1 Controller Initialization Routine 


The duties of a controller initialization routines depend on the characteristics 
of the device. For example, a controller initialization routine for a card reader 
might enable interrupts from the device by setting the interrupt-enable bit in 
the device’s control and status register (CSR). A disk’s controller initialization 
routine, on the other hand, might enable interrupts and initialize all unit- 
status registers. A controller initialization routine can typically perform any of 
the following tasks: 


e Determines if it is being called as a result of a power failure by examining 
the power bit (UCB$V_POWER in UCB$L_STS) in the UCB. A controller 
initialization routine may want to perform or avoid specific tasks when 
servicing a power failure (see Section 11.1.4). 


e Clears error-status bits in device registers. 
' A MASSBUS device driver must specify the address of its unit initialization routine in the driver dispatch table 


(using the unitinit argument to the DDTAB macro as discussed in Section 6.2). UNIBUS, Q22 bus, and generic 
VAXBI device drivers can specify the address in either the DPT or DDT. 
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¢ Initiates a device operation, such as clearing a drive or acknowledging a 
disk pack. 


e Enables controller interrupts. 


e If the controller is dedicated to a single-unit device, such as a printer, 
fills in IDB$L_OWNER and set the online bit (UCB$V_ONLINE in 
UCB$L_STS). | 


¢ Permanently allocates driver resources, such as 
— UNIBUS/Q22 bus map registers (see Section 12.2.2.2) 
— UNIBUS buffered data path (see Section 12.2.1.2) 


e Allocates a buffer from nonpaged system dynamic memory. 


Note that the permanent allocation of driver resources and the allocation of 
nonpaged pool require that the controller initialization routine fork to the 
driver’s fork IPL. This action warrants careful coordination of the activities of 
the controller and unit initialization routines, both with each other and with 
the System Generation Utility (SYSGEN). See Section 11.1.5 for a discussion 


of forking in an initialization routine. 


The controller initialization routine for a generic VAXBI device driver 

must initialize the device-specific aspects of the VAXBI device. Hardware 
initialization might include such activities as writing values to BIIC and 
device-specific registers, examining the results of the BIIC self test, mapping 
a node’s window space, building data structures to control the device, and 
linking these structures into chains of similar data structures. (Section 14.4 
extensively discusses the means by which a driver’s controller initialization 
routine performs these tasks.) 


At the time of a call to a controller initialization routine, the following 
registers contain the listed values: 


Register Value 

R4 Address of CSR 

R5 Address of IDB that describes the controller 
R6 Address of DDB associated with the controller 
R8 Address of CRB for the controller 


A controller initialization routine must preserve the contents of all registers 
except RO, R1, and R2. 


11.1.2 Unit Initialization Routine 
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A unit initialization routine is useful for initializing device-dependent fields in 
the UCB. For example, a.unit initialization routine for a disk can also specify 
disk-drive geometry (such as number of cylinders) in the UCB and wait for 
online units to spin up to speed. Unit initialization routines must set the 
online bit in the UCB (UCB$V_ONLINE) to declare the unit to be on line. 


A unit initialization routine can perform the same types of tasks as a 
controller initialization routine (see Section 11.1.1). Generally, the driver 
for a single-unit controller does not need a unit initialization routine. 


Other Driver Routines 
11.1 Initialization Routines 


At the time of a call to a unit initialization routine, the registers contain the 
following values: 


Register Value 

R3 Address of primary CSR 

R4 Address of secondary CSR; R4 is equal to R3 if there is no 
secondary CSR 

R5 Address of the device's UCB 


A unit initialization routine must preserve the contents of all registers except 
RO, R1, and R2. 


11.1.3 Initialization During Driver Loading 


Prior to calling the initialization routines within a driver, VMS takes steps to 
initialize the appropriate I/O database structures and establish the appropriate 
links between these data structures and the driver. First, during system 
initialization, VMS creates an ADP for the device adapter. For generic VAXBI 
devices and MASSBUS devices, VMS creates an ADP, CRB, and IDB for the 
device at this time. Secondly, during driver loading, VMS performs some 
additional initialization. Finally, the driver’s initialization routines are given 
an opportunity to initialize the device in a device-specific manner. 


The extent of the initialization VMS performs during driver loading depends 
upon whether the I/O database is being created, and whether the driver is 
being loaded for the first time or is replacing a driver that was previously 
loaded. 


The SYSGEN commands LOAD, AUTOCONFIGURE, and CONNECT add 
new drivers to the system configuration. The RELOAD command unloads an 
existing version of a driver and replaces it with a new one. 


The LOAD command loads the driver into nonpaged system memory but 
does not call any driver-specific routines or execute any initialization requests 
specified in DPT_STORE macro invocations. 


The AUTOCONFIGURE and CONNECT commands create and initialize 
I/O database structures associated with the device driver, call driver-specific 
initialization routines, and perform requests specified in DPT_STORE macro 
invocations. For each new device they add to the system, AUTOCONFIGURE 
and CONNECT perform the following steps: 


e Create a UCB for the device. If this is the first occurrence of device and 
controller name, the commands create a DDB, CRB, and an IDB. (Because 
the CRB and IDB for a generic VAXBI device driver or MASSBUS device 
driver have already been created by the VMS adapter initialization 
routine, a CONNECT or AUTOCONFIGURE command for such a device 
never creates these structures.) 


e Perform the initialization operations specified by the DPT_STORE macros 
within the initialization and reinitialization portions of the DPT. 


¢ Relocate all addresses in the DDT and FDT to system virtual addresses. 


¢ Call the controller initialization routine specified in the CRB, if it has 
created a CRB (or if CRB$V_UNINIT is set in CRB$B_MASK for a generic 
VAXBI device). 
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e¢ Call the unit initialization routine (if any) specified in the DDT. If no 
routine exists in the DDT, call the unit initialization routine (if any) 
specified in the CRB. 


The AUTOCONFIGURE and CONNECT command operations raise IPL to 
IPL$_POWER before calling the driver’s initialization routines. 


The RELOAD command replaces an existing driver with a new driver. The 
command loads the new driver’s code into nonpaged system memory. Unlike 
the other SYSGEN commands for driver loading, RELOAD assumes that the 
data structures associated with the driver already exist, and thus updates the 
I/O database to reflect the modified code and its different location in em 
virtual address space. It performs the following functions: 


* Calls the driver unloading routine in the old version of the driver, if one 
exists (as indicated in the unload argument of the DPTAB macro) and if 
bit DPT$V_NOUNLOAD in DPT$B_FLAGS is clear. 


The driver unloading routine must return success status in RO for 
SYSGEN to proceed with the following steps. 


¢ Deallocates the memory occupied by the old version of the driver. 
e Loads the new version of the driver. 


e Executes requests specified by DPT_STORE macro invocations in only the 
reinitialization section of the DPT in the new driver. 


¢ Relocates all addresses in the FDT and DDT to system virtual addresses. 


e Calls the controller initialization routine. 


Chapter 15 contains detailed descriptions of all SYSGEN commands related 
to device drivers. 


11.1.4 Initialization During Recovery from a Power Failure 


During recovery from a power failure, the operating system locates every 
UCB in the I/O database, by following the chain of pointers to all DDBs in 
the system (starting at IOC6GL_DEVLIST and chained by DDB$L_LINK) 
and the chain of pointers to all UCBs of the same device and controller type 
(starting at DDB$L_UCB and chained by UCB$L_LINK). For each UCB it 
finds, VMS performs the following procedure: 


1 It locates the CRB associated with the UCB (UCB$L_CRB) and 
determines whether a controller initialization routine exists for the 
device’s controller by examining CRB$L_INTD+VEC$L_INITIAL. If an 
invocation of the DPT_STORE macro loaded the address of a controller 
initialization routine into this field, VMS calls that routine. 


2 It determines whether a unit initialization routine exists for the particular 
device unit by examining the unit initialization field of the DDT (DDT$L_ 
UNITINIT). If the field does not contain an address, the system checks 


the CRB (CRB$L_INTD+VEC$L_UNITINIT).2 


* MASSBUS drivers store unit initialization routines addresses only in the DDT. 
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If either the CRB or the DDT contains a nonzero address for such a 
routine, the system calls the routine to initialize the device unit. The 
system calls only one routine; if the DDT contains an address, the address 
in the CRB is ignored. 


When called to service a power failure, driver initialization routines must 
adhere to the following rules: 


e They cannot acquire any spin locks. Controller and unit initialization 
routines are called at IPL 31 during power failure recovery to reinitialize 
I/O devices before the processors are allowed to proceed with execution 
at lower IPLs. Because processors may have been holding spin locks at 
the time of the power failure, they will not be able to release them until 
after they resume execution. As a result, spin locks are not available to 
controller and unit initialization routines. 


e They cannot perform any operation that requires the intervention of other 
processors in a VMS multiprocessing system. 


A driver initialization routine can determine if it is being called as a result of a 
power failure by examining the power bit (UCB$V_POWER in UCB$L_STS) 
in the UCB. | 


11.1.5 Forking from a Driver Initialization Routine 


If a driver initialization routine must fork to perform a thread of code that 
must synchronize with code or a structure synchronized at a lower IPL, it 
must take special care to avoid breaking that synchronization. 


First of all, because SYSGEN, under normal circumstances, immediately 
calls a driver’s unit initialization routine at IPL6_POWER after its controller 
initialization completes, the unit initialization routine must be prepared for 
the instance of a controller initialization routine that forks. Such a unit 
initialization routine would complete before the fork thread of the controller 
initialization routine resumed. 


A fork thread in a unit initialization routine (or a controller initialization 
routine in a driver without a unit initialization routine) must otherwise take 
the following precautions to avoid breaking synchronization: 


e Use either the CRB fork block, or a fork block defined in a device-specific 
extension to the UCB. The separate fork block prevents a conflict with 
the use of the normal UCB fork block by the IOFORK routine. If you are 
using a separate UCB fork block, you must not attempt to allocate the 
fork block from paged pool. 


e You should use a semaphore bit to protect against multiple forking. 
Remember that the unit initialization routine may be called repeatedly 
in the case of power failures. If the semaphore shows that a fork is in 
progress, then exit without attempting to fork. Access the semaphore bit 
using interlocked instructions (for example, BBSSI or BBCCI). 


e Invoke EXE$FORK with R5 pointing to the alternate fork block. Restore 
the original value of R5 once the fork process is active. 
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© Restore all registers on exit. Because EXE$FORK removes the caller’s 
address from the stack and returns to the caller’s caller, the unit 
initialization routine must set up a dummy caller’s caller routine to 
restore registers destroyed by EXE$FORK. 





Cancel-I/O Routine 


VMS routines call a device driver's cancel-I/O routine under the following 
circumstances: 


e When a process issues a Cancel-I/O-on-Channel system service 
(S$CANCEL) 


e When a process deallocates a device, causing the device reference count 
(UCB$W_REFC) to become zero (that is, no process I/O channels are 
assigned to the device) 


e When a process deassigns a channel from a device, using the $DASSGN 
system service? 


e When VMS performs cleanup operations as part of image termination 
by canceling all pending I/O requests for the image and closing all 
image-related files open on process I/O channels 


The VMS routine EXES$CANCEL locates the UCB for the device associated 
with a process I/O channel from a pointer in the CCB, as follows: 


channel index number — CCB — UCB 


EXE$CANCEL performs the following steps: 


1 Obtains the fork lock associated with the driver, thus raising IPL to fork 
IPL. 


2 Removes from the device’s pending-I/O queue all IRPs associated with 
the process and that channel. 


3 For a buffered-I/O read operation, clears the buffered-read function bit 
(IRP$V_FUNC) in IRP$W_STS. 


4 Sets the status code SS$_CANCEL in IRP$L_—MEDIA. 


5 Inserts the IRPs removed from the pending-I/O queue into the local 
processor’s I/O postprocessing queue. 


6 Requests a software interrupt from the local processor at IPL$_IOPOST. 


7 Calls the cancel-I/O routine specified in the DDT of the associated device 
driver (argument cancel to the DDTAB macro). EXE$CANCEL locates the 
routine using the following chain of pointers: 


UCB — DDT — cancel-I/O routine 


> Note that if the call to $DASSGN deassigns the last channel to the device, the device driver’s cancel-I/O 


routine is called a second time. Channel deassignment and last channel deassignment are both potentially 
significant events for certain devices. The former means, in effect, that a user has finished with a device and the 
latter means that all users are finished with a device. The reason code for both events is CAN$C_DASSGN. 
However, a driver's cancel-I/O routine can distinguish between the two cases by examining UCBSW_REFC. 
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The cancel-I/O routine gives the driver an opportunity to prevent further 
device-specific processing of the 1/O request currently being processed on the 
device. 


11.2.1 Context of a Cancel-I/O Routine 


When EXE$CANCEL calls the cancel-I/O routine, the local processor is at 

driver fork IPL holding the associated fork lock. As a result, the cancel-I/O 
routine can read and modify the device’s UCB. Registers at the time of the 

call contain the following values: 


Register. Value 

R2 Channel index number. 

R3 Address of current IRP. 

R4 Address of process control block (PCB) of process for which the 
$CANCEL system service is being performed. 

R5 Address of device’s UCB. 

R8 Reason for call to cancel the 1/O request. Codes that signify 


the reasons for cancellation are defined by the $CANDEF macro. 
Possible values for R8 include 


CAN$C_CANCEL Called by $CANCEL system service 


CAN$C_DASSGN Called by $DASSGN or $DALLOC system 
service 


If a cancel-I/O routine uses registers other than RO through R3, it must save 
the registers and restore them before exiting. 


Device drivers might want to base their cancel-I/O operation on whether 
the cancel-I/O request is the result of a channel deassignment (CAN$C_. 
DASSGN). For example, the terminal driver cancels out-of-band AST requests 
only if the call to its cancel-I/O routine results from a Deassign-I/O-Channel 
($DASSGN) system service call. 


11.2.2 Drivers That Need No Cancel-I/O Routine 


Some devices do not need any device-dependent processing performed for 
an I/O request; you can omit the cancel argument from the DDTAB macro. 
In this case, the DDTAB macro expansion loads the address of the VMS 
routine IOC$RETURN into the appropriate position in the DDT. The routine 
IOC$RETURN executes a single RSB instruction. 
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11.2.3 Device-Independent Cancel-I/O Routine 


Drivers can specify the VMS routine IOC$6CANCELIO as the value of the 
cancel argument in the DDTAB macro invocation. IOC$6CANCELIO cancels 
I/O to a device in the following device-independent manner: 


1 It confirms that the device is busy by examining the device-busy bit in 
the UCB status longword (UCB$V_BSY in UCB$L_STS). 


2 It locates the process-identification field in the IRP currently being 
processed on the device by using the following chain of pointers: 


UCB — IRP — process identification field 


IOC$CANCELIO confirms that the field (IRP$L_PID) contains the same 
value as the corresponding field in the PCB (PCB$L_PID). 


3 It confirms that the specified channel-index number is the same as the 
value stored in the IRP’s channel-index field (IRP$W_CHAN). 


4 It sets the cancel-I/O bit in the UCB status longword (UCB$V_CANCEL 
in UCB$L_STS). Other driver routines, such as the timeout handling 
routine, check the cancel-I/O bit to determine whether to retry the I/O 
operation or abort it. (See Section 10.2.2 for additional information.) 


11.2.4 Device-Dependent Cancel-I/O Routine 
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Drivers that include their own cancel-I/O routines must perform the first 
three steps of IOC6CANCELIO listed in Section 11.2.3 to determine whether 
the I/O request being processed originates from the process canceling I/O on 
a channel. If the three checks succeed, the cancel-I/O routine can proceed in 
a device-specific manner. For instance, a cancel-I/O routine may perform the 
following tasks: 


¢ Clear UCB$V_INT and UCB$V_TIM in the UCB status longword 
(UCB$L_STS) 


¢ Release any owned map registers, data path, and controller data channel 
e Load a status code (SS$_CANCEL, for instance) into the low word of RO 


¢ Load other status information into the high word of RO and the longword 
of R1 


e Issue the REQCOM macro to complete the request 





Error Logging Routines 
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A driver that supports error logging must satisfy the following prerequisites: 


e It must invoke the data structure definition macro $EMBDEF (located in 
SYS$LIBRARY:LIB.MLB). 


e It must use the local disk extension or local tape extension of the UCB. 


These extensions include error-log extension. (See Section A.14 for 
additional information.) 
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It must provide a means whereby error logging can be enabled for the 
device. For instance, it can use the DPT_STORE macro to set the device 
characteristic DEV$V_ELG in UCB$L_DEVCHAR or it can support an 
IO$_SETCHAR function that sets this bit. 


It must ensure that the size of the error log buffer, as specified in 
DDT$W_ERRORBUF, is large enough to accommodate EMB$L_DV_ 
REGSAV+4, plus one longword for each register to be dumped. It must 
specify this value in the erlgbf argument to the DDTAB macro. 


It should include a register dumping routine, specifying its address in the 
regdmp argument of the DDTAB macro. 


It must complete the servicing of the I/O request by invoking the 
REQCOM macro. (Routines, like ERLGDEVICEATTN, that log errors 
that are not associated with the current I/O request skip this step.) 
IOC$REQCOM takes steps to complete the error logging initiated by a 
call to an error logging routine. 


11.3.1 Error Logging Routines Supplied by VMS 


The VMS operating system provides the following routines that drivers can 
call to allocate and fill an error message buffer after a device error or timeout 


occurs: 
Routine Function 

ERL$DEVICERR Logs an error associated with the I/O request in progress 
ERL$DEVICTMO Logs a timeout associated with the |/O request in progress 


ERL$DEVICEATTN Logs an error not associated with an 1/O request 


These routines are described in full in Appendix C, but they all perform 
similar functions, as follows: 


Increment UCB$W_ERRCNT to record a device error. If the error-log- 
in-progress bit (UCB$V_ERLOGIP in UCB$L_STS) is set, the routine 
returns control to its caller (ERL$6DEVICERR and ERL$DEVICTMO only). 


Allocate from the current error log allocation buffer an error message 
buffer of the length specified in the device’s DDT (in argument erlgbf to 
the DDTAB macro). 


Initialize the buffer with the current system time, error log sequence 
number, and error type code. These routines use the following error type 
codes: . 


Routine Error Code 


ERL$DEVICERR Device error (EMB$C_DE) 
ERLSDEVICTMO Device timeout (EMB$C_DT) 
ERLSDEVICEATTN Device attention (EMB$C_DA) 


Place the address of the error message buffer in UCB$L_EMB. 
Set UCB$V_ERLOGIP in UCB$L_STS. 
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Load into RO the address of the location in the buffer in which the 
contents of the device registers are to be stored. 


Call the driver’s register dumping routine. 


11.3.2 Register Dumping Routine 
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A driver that supports error logging or diagnostics specifies the address of a 
register dumping routine in the regdmp argument to the DDTAB macro. 


When an error logging routine passes control to the driver’s register dumping 
routine, the following registers contain the listed values: 


Register Value 

RO Address of buffer into which a register dumping routine copies the 
contents of device registers 

R4 Address of device’s CSR (if the driver invoked the WFIKPCH macro 
to wait for an interrupt or timeout) 

R5 Address of UCB 


The register dumping routine preserves the contents of all registers except RO 
through R2. If it uses the stack, the register dumping routine must restore the 
stack before passing control to another routine, waiting for an interrupt, or 
returning control to its caller. 


A register dumping routine uses the following procedure to fill the indicated 
buffer: 


1 


2 


Writes a longword value representing the number of device registers to be 
written into the buffer. 


Moves device register longword values into, the buffer following the 
register count longword. 


The source of these register values depends upon the nature of the 
driver. If the driver has established a UCB extension, its interrupt service 
routine can copy to it the values of critical device registers. In this case, 
the register dumping routine may contain instructions similar to the 
following: 


MOVL UCB$L_TD_STATUS(R5) , (RO) + 


Alternatively, the register dumping routine can obtain device register 
values directly from I/O address space, offsetting from the address of the 


CSR as follows: 


MOVZWL TD_STATUS(R4) , (RO) + 


Note that this latter method is not truly accurate in that, at the time a 
register dumping routine runs, all or some device registers may have been 
modified during the servicing of device interrupts unrelated to the error. 


When a driver fork process invokes the system routine IOC$DIAGBUFILL, as 
described in Appendix C, the routine transfers control to the register dumping 
routine with the address of the diagnostic buffer in RO, the address of the 
device’s CSR in R4, and the address of the UCB in RS. 
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11.3.3 Interpreting Error Log Entries 


See the Guide to Maintaining a VMS System and the VMS Error Log Utility 
Manual for help with producing and reading error log files. 





11.4 Cloned UCB Routine 


EXE$ASSIGN calls the driver’s cloned UCB routine when an Assign I/O 
Channel system service request ($ASSIGN) specifies a template device (that 
is, bit UCB$V_TEMPLATE in UCB$L_STS is set). EXES ASSIGN does not 
assign the channel to the template device itself. Rather, it creates a copy of 
the template device’s UCB and ORB, initializing and clearing certain fields as 
appropriate. 


A cloned UCB routine receives control at IPL$_ASTDEL in kernel mode 
with process context available, holding the I/O database mutex (IOC$GL_— 
MUTEX). | 


Only drivers for network devices or template devices, such as mailboxes, 
include a cloned UCB routine. A driver specifies the address of a cloned UCB 
routine in the cloneducb argument of the DDTAB macro. 


The driver's cloned UCB routine verifies the contents of fields in the UCB and 
ORB and completes their initialization. When a cloned UCB routine is called, 
the following locations contain the listed values: 


Location 


RO 

R2 

R3 

R4 

R5 
UCB$L_FOFL(R2) 
UCB$L_FOBL(R2) 
UCB$L_FPC(R2) 
UCB$L_FR3(R2) 
UCB$L_FR4(R2) 
UCB$W_BUFQUO(R2) 
UCB$L_ORB(R2) 
UCB$L_LINK(R2) 
UCB$L_IOQFL(R2) 
UCB$L_IOQBL(R2) 
UCB$W_UNIT(R2) 


UCB$W_CHARGE(R2) 
UCB$W_REFC(R2) 
UCB$L_STS(R2) 


Contents 


SS$_NORMAL 

Address of cloned UCB 
Address of DDT 

Address of current PCB 
Address of template UCB 
Address of UCB$L_FOFL(R2) 
Address of UCB$L_FOFL(R2) 
0 

O 

0 

0 

Address of cloned ORB 
Address of next UCB in DDB chain 
Address of UCB$L_IOQFL(R2) 
Address of UCB$L_IOQOFL(R2) 


Device unit number (minimum UCBS$W_UNIT_. 
SEED(R5)+1) 


Mailbox byte quota charge (UCB$W_-SIZE) 
0 
UCB$V_DELETEUCB set, UCB$V_ONLINE set 


11-11 


Other Driver Routines 
11.4 Cloned UCB Routine 


Location 


UCB$W_DEVSTS(R2) 


UCB$L_OPCNT(R2) 
UCBS$L_SVAPTE(R2) 
UCBSW_BOFF(R2) 
UCBSW_BCNT(R2) 
UCBS$L_—ORB(R2) 


ORB$L_OWNER 
of template ORB 


ORB$L_ACL__MUTEX 
of template ORB 
ORB$B_FLAGS 
of template ORB 
ORB$W_PROT 
of template ORB 
ORB$L_ACL__COUNT 
of template ORB 
ORB$L_ACL_DESC 
of template ORB 


ORB$R_MIN_CLASS 
of template ORB 


Contents 


UCB$V_DELMBX set if DEV$V_MBx is set in 
UCB$L_DEVCHAR(R2) 


0 
0 
0 
0 
Address of cloned ORB 
UIC of current process 


FFFF 16 
ORB$V_PROT_16 set 
0 
0 
0 


O in first longword 


A cloned UCB routine must preserve the contents of R2. It issues an RSB- 
instruction to return control to EXE$ASSIGN. If the routine returns error 
status in RO, EXES$ASSIGN undoes the process of UCB cloning and completes 


with the failure status in RO. 
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Part Ill Bus Specific Considerations and Advanced 
Topics 


1 2 UNIBUS and Q22 Bus Device Support 


This chapter provides information specific to the creation of drivers for 
devices attached to the UNIBUS or Q22 bus. VMS provides extensive support 
for UNIBUS/Q22 bus drivers, including many system routines and macros 
that drivers can use to accomplish a multiblock transfer to a DMA device by 
means of UNIBUS adapter/Q22 bus interface resources. Section 12.1 explains 
the functions of the UNIBUS adapter and Q22 bus interface, describing these 
resources in detail. Section 12.2 provides a step-by-step account of how 
UNIBUS/Q22 bus device drivers can use the facilities of VMS to accomplish 
DMA transfers. 


Although the general mechanism of device interrupt dispatching, as defined 
by the VAX architecture and briefly described on Chapter 9, is the same for 
all VAX processing systems and I/O subsystems, certain implementation 
details differ. In that regard, Section 12.3 describes the means by which 
VAX hardware and the VMS operating system deliver a UNIBUS or Q22 bus 
device’s interrupt to its driver’s interrupt service routine. 


12.1 Functions of the UNIBUS Adapter and Q22 Bus Interface 


The UNIBUS adapter connects the UNIBUS, an asynchronous, bidirectional 
bus, to the backplane interconnect. The adapter performs the following 
functions: 


e Arbitrates interrupts from UNIBUS devices according to their priority 
e Delivers interrupts from UNIBUS devices to the processor 


e Allows drivers to gain access to UNIBUS device registers using system 
virtual addresses 


e Translates 18-bit UNIBUS addresses to physical addresses in main 
memory 


e Provides a data-transfer path to randomly ordered physical addresses in 
main memory 


e Provides buffered data transfer paths to consecutively increasing UNIBUS 
addresses, thus optimizing CPU-to-UNIBUS data transfers 


e Permits byte-aligned buffers for UNIBUS devices requiring word-aligned 
buffer addresses 


The Q22 bus closely resembles the UNIBUS. For MicroVAX 3600-series, 
MicroVAX II, or MicroVAX I devices attached to the Q22 bus, special 
processor logic implements a Q22 bus interface that similarly allows drivers 
access to device registers and manages device interrupts. Additional logic 
in the MicroVAX 3600-series processor or MicroVAX II processor establishes 
a scatter-gather map that translates 22-bit Q22 bus addresses to physical 
addresses. However, MicroVAX 3600-series, MicroVAX II, and MicroVAX I 
systems do not implement buffered data paths. (Table 12-1 compares the 
UNIBUS and Q22 bus I/O subsystems of the various VAX and MicroVAX 
processing systems.) 
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Table 12—1 


System 


VAX-11/780 
VAX-11/785 
VAX 8600 
VAX 8650 
VAX 8670 


The protocol a VAX system uses to enable communications between its I/O 
bus and backplane permits its devices and device drivers to exchange data 
without much awareness of the intervening hardware. First of all, both the 
UNIBUS adapter and the Q22 bus interface provide access to device registers 
using an address mapping scheme that is invisible to the driver. In addition, 
when the configuration of the I/O interface has an impact on the control of a 
data transfer, the driver can generally call one of the many VMS routines that 
handle the details of the interface. 


The functional differences between I/O adapters are irrelevant to devices 
that do not perform DMA transfers. A driver that performs non-DMA 
(programmed I/O) transfers for a device on the UNIBUS can, with no 
alteration, perform the same services for an equivalent device on a Q22 
bus. 


On the other hand, the differences between the functions of the UNIBUS 
adapter and the Q22 bus interface of the MicroVAX 3600-series, MicroVAX 
II, and MicroVAX I systems are significant to those drivers that manage DMA 
device operations. 


Section 12.2 describes the means by which device drivers set up DMA 
transfers, according to any of these interfaces. If a DMA driver that drives 
similar devices on various VAX systems must secure some measure of 
machine independence, it can include some run-time conditional code that 
branches to appropriate routines in the driver that accomplish the machine- 
dependent work. See the description of the ADPDISP macro in Appendix B 
and the sample drivers that appear in Appendixes E and F for guidance. 


This section discusses the functions of the UNIBUS adapter and the Q22 bus, 
as follows: 


e The discussion of reading and writing device registers in Section 12.1.1 
applies to UNIBUS, MicroVAX 3600-series, MicroVAX II, and MicroVAX I 
drivers. 


e The description of mapping I/O bus addresses in Section 12.1.2 pertains 
only to UNIBUS, MicroVAX 3600-series, and MicroVAX II DMA drivers. 


e The description of buffering data transfers in Section 12.1.3 relates mainly 
to UNIBUS drivers, although Section 12.1.3.1 contains information 
relevant to MicroVAX 3600-series, MicroVAX II, and MicroVAX I drivers 
as well. 


Features of the UNIBUS Adapters/Q22 Bus Interfaces of VAX Systems 


Memory 
References 
(Physical Direct Buffered Data Map Interrupt 
Adapter Address) Data Path Paths Registers Dispatcher 
UBA 30-bit (via 1, WS, 496 Non-direct-vector 
SBI) no byte- 8-byte buffer, 
aligned byte-aligned 
transfers transfers, 
LWAE,? 
prefetch 


3LWAE (longword access enable) refers to the capability to reference random longword-aligned data in a bus transfer. 
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Table 12—1 (Cont.) 


System 
VAX-—11/750 


VAX-—11/730 
VAX-—11/725 


VAX 8200 
VAX 8250 
VAX 8300 
VAX 8350 
VAX 8530 
VAX 8550 
VAX 8700 
VAX 8800 
VAX 8830 
VAX 8850 
VAX 6200 
series 


MicroVAX 
3600 series 


MicroVAX Il 


MicroVAX | 


Adapter 
UBI 


UBA 


DWBUA 
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Memory 
References 
(Physical 
Address) 


24-bit (via 
CMI) 


24-bit 


30-bit (via 
VAXBI) 


29-bit 


24-bit 


22-bit 


Direct 
Data Path 


1, 

byte- 
aligned 
transfers 


a 

byte- 
aligned 
transfers 


1, 

byte- 
aligned 
transfers 


1, 

no 
restrictions 
on data 
alignment’ 


LP 

no 
restrictions 
on data 
alignment! 


1, 

no 
restrictions 
on data 
alignment! 


Buffered Data 
Paths 


3, 

4-byte buffer,” 
byte-aligned 
transfers, 
LWAE,? 

no prefetch 


None 


5, 

8-byte buffer, 
byte-aligned 
transfers, 
LWAE,? 

no prefetch 


None 


None 


None 


Map 
Registers 


5124 


5124 


5124 


8192 


8192 


None 
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Features of the UNIBUS Adapters/Q22 Bus Interfaces of VAX Systems 


Interrupt 
Dispatcher 


Direct-vector 


‘Direct-vector 


Direct-vector 


Direct-vector 


Direct-vector 


Direct-vector 


'The MicroVAX 3600-series, MicroVAX II, and MicroVAX | implementations of the Q22 bus provide no byte-offset 
register; so, on Q22 bus devices that are only capable of word-aligned transfers, only word-aligned transfers are 


possible. 


-2Buffered data paths on the VAX—11/750 only buffer four bytes of data. Because the data paths do not perform a 
prefetch, they can always reference longwords at random. 


3LWAE (longword access enable) refers to the capability to reference random longword-aligned data in a bus transfer. 


4The VMS operating system makes available only 496 of these map registers. 
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12.1.1 Reading and Writing Device Registers 


12.1.2 Map Registers 
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Each I/O controller or device directly attached to a UNIBUS or Q22 bus has 
a control and status register (CSR) and set of data registers. These registers 
are assigned physical addresses in the 8KB allocated for this purpose from the 
256KB UNIBUS address space or in the Q22 bus I/O space. Device drivers 
obtain the device’s status and activate the device by reading and writing to 
these registers. 


Because the VMS operating system maps this I/O space into virtual address 
space, a device driver can treat the addresses of device registers as identical to 
all other virtual addresses. The driver can read and write data to the device’s 
register as though the device’s register were a location in memory. The driver 
must use instructions within the restrictions described in Section 5.2. 


Before a driver for a device that shares a controller can gain access to a 
device’s registers, it must first obtain a controller channel, as described in 
Sections 3.4.1 and 8.3.1. 


DMA devices read and write data from and to memory locations using 
18-bit UNIBUS addresses or, for the MicroVAX 3600 series, MicroVAX II, and 
MicroVAX I, 22-bit Q22 bus addresses. 


A driver that performs multiblock DMA transfers for a UNIBUS device or Q22 
bus device must set up any mapping or buffering mechanisms required by 
the system’s I/O interface. For UNIBUS DMA drivers, this involves setting 
up sufficient map registers and, perhaps, a buffered data path prior to the 
transfer. MicroVAX 3600-series and MicroVAX II DMA drivers, likewise, 
must allocate and fill a set of map registers. By contrast, MicroVAX I DMA 
drivers—because the MicroVAX I has no scatter-gather map—cannot map the 
many and scattered pages of a multiblock DMA transfer to a contiguous set of 
addresses in the I/O adapter’s address space. As a result, when it is loaded 
into the system, a MicroVAX I DMA driver must reserve enough physically 
contiguous memory to accommodate its largest possible DMA transfer (see 
Section 12.2.8). 


For UNIBUS devices and MicroVAX II/MicroVAX 3600-series devices, the 
UNIBUS adapter and the Q22 bus interface translate the bus addresses into 
main memory addresses, thus allowing the operating system, I/O drivers, 
and UNIBUS devices to access the same physical address space. DMA 
devices connected to either a UNIBUS, MicroVAX 3600-series Q22 bus, or 
MicroVAX II Q22 bus can access a block of memory indirectly by means 

of the scatter-gather map supplied by the UNIBUS adapter or MicroVAX 
processor, respectively. The map registers provided allow the device to access 
scattered, physical memory addresses as contiguous, physical addresses in 
1/O space. 


When a device driver performs a DMA transfer, it allocates map registers and 
a buffered data path (an option available to devices on the UNIBUS of some 
VAX systems), and sets up the transfer by means of the device’s registers. The 
device then accesses memory directly by means of the I/O bus, transferring 
all the data requested. When the transfer is complete, the device notifies the 
driver by requesting an interrupt. 


UNIBUS and Q22 Bus Device Support 
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Consider a buffer, for example, that consists of virtual pages 400, 401, 402, 
and 403, which are physical pages 1003, 204, 1190, and 240, respectively. 
For a UNIBUS or Q22 bus device to access this buffer, the driver requests 
four map registers, then places the physical addresses of these pages in the 
map registers. A field in each map register identifies the page-frame number 
corresponding to the UNIBUS space or Q22 bus space address that the map 
register represents (see Figure 12-1). 


Assume the driver has allocated four map registers, 127 through 130. The 
driver loads them as follows: 


Map Register Contents 
127 1003 
128 204 
129 1190 
130 240 


Note that the VMS routine the driver calls to allocate map registers 
automatically allocates an additional map register (register 131 in this case). 
The map register loading routine clears this register in order to prevent a 
runaway DMA transfer. 


The device and the UNIBUS can transfer data into or out of these physical 
pages without intervention by the driver. The device requests an interrupt 
only when all the data in these four pages has been transferred. 


Generally, a map register exists for each page of I/O space. Because the 
UNIBUS address space consists of 256K of memory, minus the 8KB reserved 
for device control registers, 496 map registers are available for UNIBUS DMA 
transfers. MicroVAX 3600-series and MicroVAX II DMA devices can use up to 
8192 of the map registers that correspond to the 4MB of Q22 bus I/O space. 


Drivers call VMS routines to fill as many map registers with valid page-frame 
numbers as needed for a DMA transfer. The DMA device puts an address on 
the I/O bus. The UNIBUS adapter or Q22 bus interface receives the address 
and translates it using the following information (see Figures 12-2 and 12-3): 


e In UNIBUS addresses, the 9-bit UNIBUS page address field (bits 9 through 
17 of the UNIBUS address) identifies the UNIBUS adapter map register. 


In Q22 bus addresses, the 13-bit Q22 bus page address field (bits 9 through 
22 of the Q22 bus address) identifies the MicroVAX II map register. 


e The page-frame-number (PFN) field in the map register specifies the 
high-order bits of the physical address. (The PFN field is 15 bits long for 
the MicroVAX II, VAX-11/750, and VAX-11/730; 20 bits long for the 
MicroVAX 3600-series systems, and 21 bits long for other VAX systems.) 
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Figure 12—1 UNIBUS and Q22 Bus Map Registers 





VAX-11/780, VAX-11/785, and VAX 8600/8650/8670 
26 25 24 2120 0 


[ reserved Hl 









page frame number 






byte offset 
longword access enable (LWAE) 


valid bit 


oe VAX-11/730, and VAX-—11/725 
26 2524 222120 1514 0 


T= I ie 


data path number (for VAX—11/750) 









page frame number 


byte offset 


longword access enable (LWAE) for compatibility with 
VAX-11/780; unused on VAX-11/750 and VAX-—11/730 
valid bit 


VAX 8200/8250/8300/8350, VAX 8530/8550/8700/8800/8830/8850, and VAX 6200 Series 
313029 2726252423 2120 0 


it cit | 


page frame number 





byte offset 
longword access enable (LWAE) 
valid bit 


MicroVAX II 
3130 1514 0 


reserved page frame number 





MicroVAX 3600 Series 
3130 . 2019 0 


reserved page frame number 





2K-4842-85 
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e From UNIBUS addresses, bits 2 through 8 map to bits 0 through 6 of the 
physical address.! The resulting physical address locates the longword 
that is the target of the transfer. 


From Q22 bus addresses, bits 0 through 8 map to bits 0 through 8 of the 
physical address. The resulting physical address locates the byte that is 
the target of the transfer. 


Each UNIBUS adapter or Q22 bus map register also contains a bit called the 
map-register valid bit. The UNIBUS adapter or Q22 bus interface tests this 
bit every time the map register is used. If the bit is not set, the UNIBUS 
adapter or Q22 bus interface aborts the transfer. This bit is clear whenever 
the register is not mapped to a physical address. 


Figure 12—2 Mapping a UNIBUS Address to a Physical Address 


18-BIT UNIBUS ADDRESS 


, longword 
map register number 





UNIBUS 
adapter 
scatter-gather 
map 










32-BIT MAP REGISTER 


Pe aia eli sataes 







page frame number 
offset 


PHYSICAL ADDRESS 
ZK-915-82 


' The disposition of the lowest two bits of the UNIBUS address depends on the VAX system. For instance, the 
VAX-11/780 uses them to construct a byte-selection mask and function to be transmitted across UNIBUS lines 
that modify the I/O transaction. 
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Figure 12—3 Mapping a Q22 Bus Address to a Physical Address 


22-BIT Q22 BUS ADDRESS 


map register number byte offset ie 









scatter-gather 
map 





32-BIT MAP REGISTER 


bose ad adi eee 





page frame number 


24-BIT PHYSICAL ADDRESS (MicroVAX Il) 


29-BIT PHYSICAL ADDRESS 
(MicroVAX 3600 Series) 


ZK-4841-85 


12.1.3 UNIBUS Adapter Data Transfer Paths 


The UNIBUS adapter sends data through one of several data paths for 
UNIBUS devices performing DMA transfers. One data path, the direct data 
path (DDP), allows UNIBUS transfers to randomly ordered physical addresses. 
The direct data path maps each UNIBUS transfer to a backplane interconnect 
transfer. Thus, a single word or byte of data is transferred for each backplane 
interconnect operation. 


The remaining data paths, the buffered data paths (BDPs), allow devices on the 
UNIBUS to transfer more efficiently than through the direct data path. The 
buffered data paths store UNIBUS data so that multiple UNIBUS transfers 
result in a single backplane interconnect transfer. 


When a UNIBUS device begins a DMA transfer by placing an address on 
the UNIBUS, the UNIBUS adapter not only performs address mapping 
but also provides the number of the data path to be used for the transfer 
(see Figure 12-1). Each UNIBUS adapter map register contains a field that 
describes the data path. Data path 0 is the direct data path; the other data 
paths are the buffered data paths. (The UNIBUS data path registers of the 
various VAX systems are pictured in Figure 12-4.) 


The following sequence describes a UNIBUS-device DMA transfer. 
1 The UNIBUS device puts an address on the UNIBUS. 


2 The UNIBUS adapter locates the UNIBUS adapter map register that 
corresponds to the UNIBUS address. 
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Figure 12—4 UNIBUS Data Path Registers 





VAX-11/780, VAX 8600, VAX 8650, and VAX 8670 
31 30 29 28 23 15 0 


UNIBUS address 


S172 





data path function 
buffer transfer error 


buffer not empty/purge 


VAX-11/750 
31 30 29 28 1 0 





uncorrectable error 
nonexistent memory error 


error summary 


VAX 8200/8250/8300/8350, VAX 8530/8550/8700/8800/8830/8850, and VAX 6200 Series 
DATA PATH CONTROL/STATUS REGISTER 


31 2423 2120 1 0 


select 





ADDRESS/STATUS REGISTER 
31 1615 ) 


buffer address 





ZK-4843-85 





3 The UNIBUS adapter verifies that the map register has the map-register 
valid bit set. 


4 The UNIBUS adapter maps the UNIBUS address to a physical address. 


5 The UNIBUS adapter extracts the number of the data path to be used for 
the transfer from the map register. 


6 The UNIBUS adapter translates the UNIBUS function to a backplane 
interconnect function by reading the UNIBUS control lines. 
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7 Based on the UNIBUS function indicated by the UNIBUS control lines, 
(DATI, DATIP, DATO, or DATOB), the UNIBUS adapter starts appropriate 
UNIBUS and backplane interconnect operations to transfer data between 
the UNIBUS device and memory. 


Direct Data Path 

Since the direct data path performs a backplane interconnect transfer for 
every I/O bus transfer, it can be used by more than one UNIBUS or Q22 bus 
device at a time. The UNIBUS adapter or Q22 bus interface arbitrates among 
devices that wish to use the direct data path simultaneously. The device 
driver is unaffected by this arbitration. 


The direct data path is less efficient than a buffered data path because each 
I/O bus transfer cycle corresponds to a backplane interconnect cycle. One 
word.or byte is transferred for each backplane interconnect cycle. On some 
hardware configurations, the direct data path is unable to transfer a word of 
data to an odd-numbered physical address. Therefore, an FDT routine for 
a DMA device that uses the direct data path should check that the specified 
buffer is on a word boundary.” 


The Q22 bus systems only employ a direct data path. A UNIBUS device 
driver may choose to use a direct data path rather than a buffered data path 
to perform the following functions: _ 


e Execute an interlock sequence to the backplane interconnect (DATIP- 
DATO/DATOB) 


e Transfer to randomly ordered addresses instead of consecutively 
increasing addresses 


e Mix read and write functions 


The direct data path is the simplest data path to program. Since the direct 
data path can be shared simultaneously by any number of I/O transfers, the 
device driver does not need to call a VMS routine to allocate the data path. 
Instead, the driver performs the following actions: 


1 Uses the REQMPR macro to allocate a set of map registers (or the 
REQALT macro to allocate a set of Q22 bus alternate map registers 
(registers 496 to 8191)). 


2 Uses the LOADUBA macro (or LOADALT macro) to load the 
map registers with physical address map data and, for UNIBUS 
devices, the number of the direct data path (0). The VMS routines 
called in the expansion of these macros (IOC$LOADUBAMAP and 
IOC$LOADALTMAP respectively) also set the valid bit in every map 
register except the last, which remains invalid to prevent a runaway 
transfer. 


3 Loads the starting address of the transfer in a device register. 
4 Loads the transfer byte or word count in a device register. 


5 Sets bits in the device CSR to initiate the transfer. 


* The MicroVAX 3600-series, MicroVAX II, and MicroVAX I implementations of the Q22 bus provide no 
byte-offset register. As a result, for Q22 bus devices that are only capable of word-aligned transfers, only 
word-aligned transfers are possible. 
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12.1.3.2 


Buffered Data Paths 

When a buffered data path is used, the UNIBUS adapter transfers data much 
more efficiently between the UNIBUS and the backplane interconnect than 
when a direct data path is used. It accomplishes this by decoupling the 
UNIBUS transfer from the backplane interconnect transfer. The buffered data 
path allows the UNIBUS adapter to read or write multiple words of data in a 
transfer, and buffer the unrequested portions of the data in a UNIBUS adapter 
buffer. Thus, several UNIBUS read functions can be accommodated with a 
single backplane interconnect transfer. 


Q22 bus systems do not employ buffered data paths. The writer of a UNIBUS 
device driver may choose to use a buffered data path rather than a direct data 
path to perform the following functions: 


e Faster DMA block transfers to or from consecutively increasing UNIBUS 
addresses 


¢ Word-oriented block transfers that begin and end on an odd-numbered 
byte of memory; note, however, that these transfers can be quite slow 
because the UNIBUS adapter might need to perform multiple transfers to 
complete a one-word transfer 


e¢ 32-bit data transfers from random longword-aligned physical addresses 


A single buffered data path cannot be assigned to more than one active 
transfer at a time. When a driver fork process is preparing to transfer data 
to or from a UNIBUS device on a buffered data path, it performs a sequence 
of steps similar to those performed by a driver that uses the direct data path, 
with the exception that it uses a macro that calls a VMS routine that allocates 
a free buffered data path. The following are among the actions of the driver 
fork process: 


1 Uses the REQMPR macro to allocate a set of map registers. 
2 Uses the REQDPR macro to allocate a free buffered data path. 


3 Uses the LOADUBA macro to load the map registers with physical 
address mapping data and the number of the allocated buffered data 
path. The VMS routine called in the expansion of the LOADUBA macro 
(IOCSLOADUBAMAP) also sets the valid bit in every map register except 
the last, which remains invalid to prevent a runaway transfer. 


4 Loads the starting address of the transfer in a device register. 
5 Loads the transfer byte or word count in a device register. 


6 Sets bits in the device CSR to initiate the transfer. 


The UNIBUS adapter hardware of certain VAX systems normally restricts 
buffered data paths to referring only to consecutively increasing UNIBUS 
addresses. Through a special mode of operation, these UNIBUS adapters can 
also refer to 32-bit data at randomly-ordered, longword-aligned locations in 
physical memory. Other systems do not impose this restriction. In order for a 
device driver to run on both types of systems, it must observe three rules: 


e All transfers within a block must be of the same function type (DATI or 
DATO/DATOB). 


e Buffered data paths must always transfer data to consecutively increasing 
addresses. 
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e To reference 32-bit data at random, longword-aligned locations in 
physical memory, the longword-access-enable bit (LWAE) must be set. 


A buffered data path stores data from the UNIBUS in a buffer until multiple 
words of data have been transferred (except in longword-aligned, 32-bit, 
random-access mode as discussed in Section 12.1.3.5). Then, the UNIBUS 
adapter transfers the contents of the buffer to the appropriate physical address 
in a single backplane interconnect operation. The procedure for a UNIBUS 
write operation that transfers data from a device to memory is broken into 
individual steps. 


1 The UNIBUS device transfers one word of data to the buffered data path. 


2 The UNIBUS adapter stores the word of data and completes the UNIBUS 
cycle. 


3 The UNIBUS adapter sets the buffer-not-empty flag in the buffered data 


path to indicate that the buffer contains valid data. 
4 The UNIBUS device repeats the first three steps until the buffer is full. 


5 When the UNIBUS device addresses the last byte or word in the buffer, 
the UNIBUS adapter recognizes a complete data-gathering cycle. 


6 The UNIBUS adapter requests a write function on the backplane 
interconnect to write the data from the buffered data path to memory. 


7 When the backplane interconnect transfer is complete, the buffered data 
path clears its flag to indicate that the buffer no longer contains valid 
data. 


The procedure for a UNIBUS read operation that transfers data from main 
memory to a device varies according to the type of UNIBUS adapter. Those 
adapters that can perform a prefetch function complete UNIBUS reads 
from memory more quickly than those that cannot. The prefetch feature 
accomplishes this improved performance by automatically filling the data 
path buffer after the buffer’s contents are transferred to the UNIBUS. 


The following paragraphs discuss the UNIBUS read operation with and 
without the prefetch function. Device drivers that adhere to the conventions 
outlined in this manual will execute properly whether or not the device is 
associated with a UNIBUS adapter that is capable of prefetches. 


1 The UNIBUS device initiates a read operation from a buffered data path. 
2 The UNIBUS adapter checks to see if its buffers contain valid data. 


3 If the buffers do not contain valid data, the buffered data path initiates 
a read function to fill the buffers with data from main memory. The 
transfer completes before the UNIBUS adapter begins a UNIBUS transfer. 


4 The UNIBUS adapter transfers the requested bytes to the UNIBUS. Bytes 
of data that were not transferred to the UNIBUS remain in the buffer. 


5 The UNIBUS adapter sets the buffer-not-empty flag in the buffered data 
path to indicate that the buffer contains valid data. 


6 When the UNIBUS device empties the buffers of the buffered data path 
with a UNIBUS read function that accesses the last word of data, the 
buffered data path clears the buffer-not-empty flag to indicate that the 
buffer no longer contains valid data. 


UNIBUS and Q22 Bus Device Support 
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12.1.3.3 


12.1.3.4 


7 The buffered data path then initiates a read function to prefetch data from 
memory. 


8 When the prefetch is complete, the buffered data path sets the buffer-not- 
empty flag to indicate that the buffers now contain valid data. 


The prefetch might attempt to read data beyond the address mapped by the 
final map register. To avoid referring to memory that does not exist, the 
VMS routines that allocate and load map registers always allocate one extra 
map register and clear the map-register-valid bit before initiating the transfer. 
When the UNIBUS adapter notices that the map register for the prefetch is 
invalid, the UNIBUS adapter aborts the prefetch without reporting an error. 


A UNIBUS read function without prefetch includes the following steps: 
1 The UNIBUS device initiates a read operation from a buffered data path. 
2 The buffered data path checks to see if its buffers contain valid data. 


3 If the buffers do not contain valid data, the buffered data path initiates a 
read function to fill the buffers with data. The transfer completes before 
the UNIBUS adapter begins a UNIBUS transfer. 


4 The buffered data path transfers the requested bytes to the UNIBUS. 
Bytes of data that were not transferred to the UNIBUS remain in the 
buffer. 


Byte-Offset Data Transfers 

The UNIBUS adapter has a byte-offset register; thus, words that are not 
word-aligned can be transferred to and from any device on the UNIBUS 
regardless of whether the device supports non-word-aligned transfers. 


Some UNIBUS devices are restricted to transferring integral words of data 

in word-aligned UNIBUS addresses. The buffered data paths allow these 
devices to perform transfers to memory that begins and ends on an odd-byte 
address. A byte-offset bit in the map registers indicates byte-aligned data to | 
the hardware. If the bit is set, the hardware increments physical addresses. 

A VMS subroutine that loads map registers determines whether the data is 
word- or byte-aligned and sets the byte-offset bit accordingly. 


Purging a Buffered Data Path 

Because prefetches can read more data from memory than the UNIBUS device 
wishes to read, driver fork processes must ask the UNIBUS adapter to purge 
the buffered data path when a transfer is complete. In addition, a transfer 
from a device to the backplane interconnect can complete with some data left 
in the buffer. The driver must purge the data path to complete the transfer. 


The purge guarantees that the data is not transferred to the next user of the 
buffered data path. The driver fork process performs the purge by calling a 
standard VMS routine that performs two functions: 


e Tells the hardware to purge the buffered data path register owned by the 
fork process. For a UNIBUS read function, the adapter simply clears the 
buffer-not-empty flag. For a UNIBUS write function, the adapter transfers 
any data left in the data path buffer to VAX memory, then clears the flag. 


¢ Notifies the driver fork process of any error that occurs during the purge. 


The data path must be purged before the driver releases map registers or the 
buffered data path register. 
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12.1.3.5 


Longword-Aligned, 32-Bit, Random-Access Mode 

Another method of transferring data over a buffered data path is the use 

of longword-aligned, 32-bit, random-access mode. This mode essentially 
prevents the UNIBUS prefetch operation, thereby allowing a device that reads 
data from or writes data to memory to reference longword-aligned locations 
in memory at random, in longword multiples. 


To transfer data in the longword-aligned, 32-bit, random-access mode, the 
driver fork process sets the longword-access-enable bit (VEC$V_LWAE) in the 
channel request block (CRB) prior to loading the map registers. The UNIBUS 
device can then perform a read (DATI) or write (DATO) function. 


For a UNIBUS read operation that transfers data from n main memory to a 
device, the function occurs as follows: 


1 The driver fork process initiates a read function on the UNIBUS device. 


2 The UNIBUS adapter clears the buffer-not-empty flag in the assigned 
buffered data path. 


3 The UNIBUS adapter requests a read-from-memory operation on the 
backplane interconnect. 


4 The UNIBUS adapter stores the longword of data in the buffered data 
path and sets the buffer-not-empty flag. 


5 The UNIBUS adapter completes two UNIBUS read operations to transfer 
two words of data. 


For a UNIBUS write operation that transfers data from a device to main 
memory, the function occurs as follows: 


1 The driver fork process initiates a write function on the UNIBUS device. 


2 The UNIBUS adapter clears the buffer-not-empty flag in the assigned 
buffered data path. 


3 The UNIBUS adapter completes two write operations to transfer two 
words of data from the UNIBUS device. 


4 The UNIBUS adapter stores the longword of data in the data path’s buffer 
and sets the buffer-not-empty flag. 


5 The UNIBUS adapter initiates a backplane interconnect write operation. 


6 When the backplane interconnect write operation is complete, the 
UNIBUS adapter clears the buffer-not-empty flag. 


To ensure that random-access mode works correctly regardless of the VAX 
system involved, the writer of a device driver should ensure that a device 
assigned to a buffered data path does not repeatedly address the same 
longword. On certain systems, a UNIBUS device that polls a single longword, 
waiting for data, will constantly be returned the same data. 
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12.2 Writing Driver Code for UNIBUS/Q22 Bus DMA Transfers 


A driver performing DMA transfers over the UNIBUS or Q22 bus must take 
I/O bus operation into consideration. The VMS operating system and the 
I/O database manage the map registers and data path resources of the I/O 
adapter for device drivers. 


The I/O database contains an adapter control block (ADP) that describes the 
I/O adapter. This block contains allocation information for the map registers; 
for UNIBUS adapters, the ADP also contains similar information for data 
paths. 


The ADP also contains the virtual address of the adapter’s configuration 
register. All the adapter’s other registers are located at fixed offsets from 
the configuration register. The VMS adapter-handling routines modify the 
adapter’s map registers and data-path register according to requests from the 
driver fork process. 


In general, a driver fork process does not directly access the ADP. Instead, a 
driver calls VMS routines that perform adapter-related services, such as the 
following: 


e §=©Allocating a buffered data path 

e Allocating map registers or alternate map registers 

e Loading map registers or alternate map registers 

¢ Deallocating map registers or alternate map registers 
e Purging a buffered data path 

e Deallocating a buffered data path 


The critical responsibility of device drivers that actively compete for such 
shared I/O adapter resources as map registers and data paths is to ensure the 
synchronized access of adapter resources. Drivers that share these resources 
must execute at the same fork IPL. In a VMS multiprocessing system, they 
must additionally contend for the same fork lock. A given driver code thread 
that must attempt to access its fork database can only do so if suitably 
synchronized. 


The system creates a driver fork process by calling the start-I/O routine in 
a device driver. The fork process takes some or all of the following steps 
to initiate an I/O transfer to or from a device on a UNIBUS, MicroVAX 
3600-series Q22 bus, MicroVAX II Q22 bus, or MicroVAX I Q22 bus. 
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Operation Applicable to 
Requests buffered data path UNIBUS 
Requests map registers UNIBUS, MicroVAX 3600 series, 
MicroVAX Il 
Requests alternate map registers MicroVAX 3600 series, MicroVAX Il 
Loads map registers UNIBUS, MicroVAX 3600 series, 
MicroVAX Il 
Loads alternate map registers MicroVAX 3600 series, MicroVAX Il 
Calculates starting bus address UNIBUS, MicroVAX 3600 series, 
. MicroVAX Ii, MicroVAX | 
Activates device UNIBUS, MicroVAX 3600 series, 
MicroVAX Il, MicroVAX | 
Waits for interrupt UNIBUS, MicroVAX 3600 series, 


MicroVAX Il, MicroVAX | 


When a hardware interrupt indicates that the I/O transfer is complete, the 
driver fork process checks the success or failure of the transfer. The driver 
then concludes with the following steps: 


Operation Applicable to 

Purges data path . UNIBUS, MicroVAX 3600 series, 
MicroVAX Il, MicroVAX 1" 

Releases buffered data path UNIBUS 

Releases map registers UNIBUS, MicroVAX 3600 series, 
MicroVAX Il 

Releases alternate map registers MicroVAX 3600 series, MicroVAX Il 


‘Regardless of whether the associated VAX system provides buffered data paths, drivers 

of all devices should initiate a purge of the data path after a transfer. The purge operation 
enables the detection of memory parity errors that may have occurred during the transfer, 

as described in the sections on the PURDPR macro and IOC$PURGDATAP in Appendixes B 
and C, respectively. 


Because of the different requirements of DMA transfers on different VAX and 
MicroVAX systems, a driver must contain some run-time conditional code in 
order to function for equivalent UNIBUS, MicroVAX 3600-series, MicroVAX 
II, and MicroVAX I devices. Appendix E contains an example of one driver 
that supports the RL11 on the UNIBUS and the RLV11 on the MicroVAX I 
and MicroVAX II Q22 bus. 


Regarding the material presented in this section, UNIBUS driver writers 
should read Sections 12.2.1 through 12.2.7.3. MicroVAX 3600-series and 
MicroVAX II driver writers should read Section 12.2.1.3 and Sections 
12.2.2 through 12.2.7.3. MicroVAX I driver writers should turn directly to 
Section 12.2.8. Because the MicroVAX I provides no scatter-gather map, 
MicroVAX I device drivers must perform transfers according to the method 
described therein. 
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12.2.1 Selecting and Requesting a Data Path 


12.2.1.1 


DMA device drivers for certain VAX systems can elect to request the use of a 
UNIBUS adapter buffered data path to accelerate data transfers (as described 
in Section 12.1.3). Other VAX processing systems, such as the MicroVAX 
3600 series, MicroVAX II and VAX-11/730, provide no buffered data paths 
for data transfers. The descriptions of the direct data path in the following 
sections apply to drivers written for devices in those systems. 


Requesting a Buffered Data Path 

Some VAX systems allow UNIBUS drivers to request temporary or permanent 
allocation of a buffered data path (see Table 12-1). After the driver fork 
process gains access to the controller (see Section 8.3.1), it requests a 
buffered data path by invoking the VMS macro REQDPR. REQDPR calls 

a VMS routine named IOC$REQDATAP that locates the ADP. To do this, 
IOC$REQDATAP uses a series of pointers that begins in the current unit 
control block (UCB), as follows: 


UCB — CRB — ADP 


IOC$REQDATAP performs the following services: 


1 Tests the path-lock bit (VEC$V_PATHLOCK) in the data-path number 
field of the channel request block (CRB$L_INTD+VEC$B_DATAPATH). 
If the device has a permanent data path allocated to it, IOC6REQDATAP 
simply returns. 


2 Determines which data paths are available by examining the data path 
allocation information in the ADP (ADP$W_DPBITMAP). 


3  Allocates the first free data path to the driver by inserting its number 
in the data path field of the CRB (CRB$L_INTD+VEC$B_DATAPATH) 
and indicating in the ADP that the data path is in use (by clearing the 
appropriate bit in ADP$W_DPBITMAP). 


4 Returns control to the driver fork process. 


If no data path is available, IOC$REQDATAP saves driver context (R3, R4, 
and PC) in the UCB fork block and inserts the address of the fork block, 
which is also the address of the UCB and the content of R5, in the ADP’s 
data-path wait queue. The driver fork block remains in the queue until both 
of the following conditions are met: 


e A data path is available. 


e The driver fork block is the next entry in the data-path wait queue. 


When these conditions are met, the VMS routine IOC6RELDATAP allocates 
the data path to the suspended driver and reactivates the driver fork process. 
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12.2.1.2 


12.2.1.3 


Requesting a Permanent Buffered Data Path 

A device driver can permanently allocate a buffered data path in its unit 
initialization routine. Instead of using the REQDPR macro, however, the unit 
initialization routine should perform the following steps: 


1 Issue the FORK macro to drop IPL to fork IPL. The VMS fork dispatcher 
causes the following steps to be performed at fork IPL under the 
ownership of the required fork lock in a VMS multiprocessing system. 
(The consequences of forking in a unit initialization routine are discussed 
at length in Section 11.1.5.) 


2 Test the path-lock bit (VEC$V_PATHLOCK) in the data-path-number 
field of the CRB (CRB$L_INTD+VEC$B_DATAPATH) to ensure that a 
data path is not already allocated for this device. 


3 Call the subroutine IOC$REQDATAPNW to allocate the data path as ~ 
follows: 


JSB G*IOC$REQDATAPNW 


If IOCSREQDATAPNW successfully allocates the data path, it stores 
the number of the data path it obtained in the CRB at CRB$L_ 
INTD+VEC$B_DATAPATH and returns with the low-order bit set in RO 
(SS$_NORMAL). If it cannot allocate a data path, IOCSREQDATAPNW 
does not create a fork process to wait for one to become available. 
Instead, it returns to the unit initialization routine with the low-order bit 
clear in RO. 


4 If the data path has been successfully obtained, set the path-lock bit 
(VEC$V_PATHLOCK) in the CRB at CRB$L_INTD+VEC$B_DATAPATH. 


The driver-loading procedure calls the unit initialization routine for each unit 
that the driver serves. A unit initialization routine that contains the code 
described previously will permanently allocate one buffered data path for 
each CRB associated with the driver, which is one path for each controller 
that the driver serves. 


Because some VAX systems have few buffered data paths (refer to 

Table 12-1), device drivers running in these systems must limit their 
allocation of permanent buffered data paths. For example, if the drivers 
loaded on a VAX-11/750 permanently allocated all three of the system’s 
buffered data paths, none would remain for normal system operations. As a 
result, I/O transfers requiring a buffered data path would wait forever. 


Requesting the Direct Data Path 

Because the UNIBUS adapter or Q22 bus interface arbitrates among devices 
that wish to use the direct data path and initializes the data path field in the 
CRB (CRB$L_INTD+VEC$B_DATAPATH) to 0 (0 = direct data path), drivers 
are not required to invoke the REQDPR macro to request the direct data path. 


Some VAX systems, such as the VAX-11/780 or VAX 8600, do not permit 
byte-offset transfers on the direct data path (see Table 12-1). Because the 
UNIBUS itself is word-oriented, such a system must ensure that the data 

buffer is aligned on a word boundary for word-aligned devices. 
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12.2.1.4 


Mixed Use of Direct and Buffered Data Paths 

A UNIBUS device driver can use the buffered data path for certain operations, 
then use the direct data path for other operations. To accomplish this task, 
the driver should allocate a buffered data path for buffered I/O. When the 
operation is completed, the driver should then purge and release the buffered 
data path. The release automatically resets the data path number to zero, 
which signifies a direct data path. When the driver has finished using the 
direct data path, it should purge it (but not release it). (A purge of the direct 
data path is a NOP and always yields success.) 


12.2.2 Requesting Map Registers 


12.2.2.1 


The UNIBUS adapter and Q22 bus interface allow UNIBUS and Q22 bus 
drivers, respectively, to allocate map registers as needed or to allocate them 
permanently. 


Allocating Map Registers 

After the driver fork process gains access to the controller (see Section 8.3.1), 
it can request a set of adapter map registers (registers 0 through 495) 

by invoking the VMS macro REQMPR. This macro calls the routine 
IOC$REQMAPREG. IOC$REQMAPREG calculates the number of map 
registers needed for a transfer, allocating one map register for each full 

or partial page of the buffer (based on the values of UCBSW_BCNT and 
UCB$W_BOFF). In addition, it reserves an additional map register to be 
marked invalid to stop a potential runaway transfer and inhibit prefetches 
from the page past that in which the end of the buffer resides. Finally, 
IOC$REQMAPREG may allocate one more extra map register to ensure that 
an even number of map registers is allocated. 


The procedure for allocating map registers is similar to that used to allocate a 
buffered data path. First, IOC6REQMAPREG locates the ADP from a series 
of pointers that begins with the current UCB, as follows: 


UCB — CRB — ADP 


Then, the routine examines the map-register-allocation information to locate 
the required number of contiguous map registers. If the registers are not 
currently available, IOC6REQMAPREG saves the driver context (R3, R4, and 
PC) in the UCB fork block and inserts the fork block’s address (same as UCB 
address and the contents of R5) in the standard-map-register wait queue. 


When the map registers are available, IOCS6REQMAPREG allocates them and 
adjusts the appropriate information about the allocation of map registers in 
the ADP. IOC$SREQMAPREG then writes the number of the first map register 
and the number of map registers allocated into the CRB and returns control 
to the driver fork process. 


VMS supplies a similar macro (REQALT) and routine IOC$REQALTMAP) 
that MicroVAX 3600-series or MicroVAX II drivers can use to allocate a 

set of alternate map registers (registers 496 through 8191). REQALT and 
IOC$REQALTMAP perform the allocation in the same manner as REQMPR 
and IOC6REQMAPREG. Note that, although VMS records the allocation 

of standard and alternate map registers in separate areas of the ADP and 
CRB, IOC$6REQMAPREG and IOC$REQALTMAP use the same UCB fields to 
calculate the number of map registers required for a transfer. 
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12.2.2.2 


Permanently Allocating Map Registers 

A device driver can allocate a permanent set of map registers with code in its 
unit initialization routine. The number of map registers permanently allocated 
must be sufficient for the largest possible transfer and must include an extra 
map register to be marked invalid to prevent a runaway transfer. 


A unit initialization routine performs the following steps to permanently 
allocate a set of map registers: 


1 


Issue the FORK macro to drop IPL to fork IPL. The VMS fork dispatcher 
causes the following steps to be performed at fork IPL under the 
ownership of the required fork lock in a VMS multiprocessing system. 
(The consequences of forking in a unit initialization routine are discussed 
at length in Section 11.1.5.) 


Test the map-lock bit (VEC$V_MAPLOCK) in the CRB (CRB$L— 
INTD+VEC$W_MAPREG) to ensure that map registers are not already 
allocated for this device. 


Load the number of map registers required into R3. 
Call the VMS routine IOC$ALOUBAMAPN with a JSB instruction: 
JSB G*IOC$ALOUBAMAPN 


If IOC6ALOUBAMAPN successfully allocates. the map registers, it stores 
the number of map registers allocated and the number of the first of 

the allocated map registers at CRB$L_INTD+VEC$B_NUMREG and 
CRB$L_INTD+VEC$W_MAPREG, respectively. It then returns with the 
low-order bit set in RO. Otherwise, it returns with the low-order bit of RO 
clear. 


If map registers have been successfully allocated, set the map-lock bit in 
the CRB (VEC$V_MAPLOCK in CRB$L_INTD+VEC$W_MAPREG). 


MicroVAX 3600-series drivers and MicroVAX II drivers perform the following 
steps to allocate a permanent set of alternate map registers (registers 496 
through 8191): 


1 


Issue the FORK macro to drop IPL to fork IPL. The VMS fork dispatcher 
causes the following steps to be performed at fork IPL under the 
ownership of the required fork lock in a VMS multiprocessing system. 
(The consequences of forking in a unit initialization routine are discussed 
at length in Section 11.1.5.) 


Test the alternate-map-lock bit (VEC$V_ALTLOCK) in the CRB (CRB$L— 
INTD+VEC$W_MAPALT) to ensure that alternate map registers are not 
already allocated for this device. 


Load the number of alternate map registers required into R3. 
Call the VMS routine IOC6ALOALTMAPN with a JSB instruction: 
JSB G7 IOC$ALOALTMAPN 


If IOC6ALOALTMAPN successfully allocates the alternate map registers, 
it stores the number of map registers allocated and the number of the first 
of the allocated map registers in CRB$L_INTD+VEC$W_NUMALLT and 
CRB$L_INTD+VEC$W_MAPALLT, respectively. It then returns with the 
low-order bit set in RO. Otherwise, it returns with the low-order bit of RO 
clear. 
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5 If alternate map registers have been successfully allocated, set the 
alternate-map-lock bit in the CRB (VEC$V_ALTLOCK in CRB$L_— 
INTD+VEC$W_MAPAL1T). 


The driver-loading procedure calls the unit initialization routine once for each 
unit associated with the driver. If the unit initialization routine contains the 
code described previously, it permanently allocates a set of map registers 

for each CRB associated with the driver, which is a set of registers for each 
device controller that the driver serves. Because VMS records the allocation of 
standard and alternate map registers in separate areas of the ADP and CRB, a 
MicroVAX 3600-series or MicroVAX II driver could permanently allocate a set 
of registers from both areas. 


12.2.3 Loading Map Registers 


Once a driver fork process has assigned a data path and allocated a set of map 
registers, it can request VMS to load the map registers with physical page- 
frame numbers (PFNs) by invoking the VMS macro LOADUBA.? LOADUBA 
calls the VMS routine IOC6LOADUBAMAP to load each allocated map 
register with the following data items: 


e A bit setting to indicate whether the map register is valid. 


e A bit setting to indicate whether the transfer is to start on the odd or even 
byte within a word; this bit is set if the low-order bit of UCBSW_BOFF is 
al. 


e The number of the data path to use for the transfer (UNIBUS drivers 
only). 


e¢ The page-frame number of a page in memory. 


e A bit setting to indicate that the transfer operates in longword-aligned, 
random-access mode on the buffered data path; this bit is set when 
VEC$V_LWAE is set in VEC6B_DATAPATH (UNIBUS drivers only). 


IOC$LOADUBAMAFP loads the PFN of the first page of the transfer into 

the first allocated map register, the PFN number of the second page of the 
transfer into the second map register, and so forth. IOC6LOADUBAMAP sets 
the valid bit in every allocated map register except the last. It clears the valid 
bit in the final map register to prevent a prefetch from an invalid page. 


To calculate the PFN used in the I/O transfer, IOC6LOADUBAMAP uses 
three fields that VMS has written into the UCB: 


e UCBSW_BOFF—Byte offset in the first page of the transfer 
¢ UCBSW_BCNT—Number of bytes to transfer 


¢ UCB$L_SVAPTE—Virtual address of the page-table entry that contains 
the PEN of the first page of the transfer 


3 MicroVAX 3600-series and MicroVAX If DMA driver writers also use the LOADUBA macro to load a set of 
standard map registers (registers 0 through 495). 
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IOC$LOADUBAMAP determines the data path’s number (for UNIBUS 
devices), the number of the first map register, the address of the first map 
register, and the number of allocated map registers from the CRB and the 
ADP, as follows: 


UCB — CRB — number of the data path 

UCB — CRB — number of first map register 

UCB — CRB — ADP — virtual address of first map register 
UCB — CRB — number of map registers 


When IOC$LOADUBAMAP has loaded all the map registers and marked the 
last map register invalid, it returns control to the driver fork process. 


VMS supplies a similar macro (LOADALT) and routine 
(IOC$LOADALTMAP) that MicroVAX 3600-series or MicroVAX II drivers 
can use to load a set of previously allocated alternate map registers (registers 
496 through 8191). LOADALT and IOC$6LOADALTMAP load the alternate 
map registers in the same manner as LOADUBA and IOC${LOADUBAMAP 
load standard map registers. 


Drivers that handle UNIBUS byte-addressable devices call the routine 
IOC$LOADUBAMAPA. This routine performs the same function as 
IOC$LOADUBAMAP, with one exception. When IOC(LOADUBAMAPA 
loads map registers, it clears the byte-offset bit even if the transfer begins on 
an odd-byte address. 


12.2.4 Computing the Starting Address of a Transfer 


The driver fork process must calculate the starting address of a DMA transfer 
and load this address into the appropriate device register. MicroVAX I device 
drivers perform the procedure outlined in Section 12.2.8. UNIBUS drivers 
and other Q22 bus drivers that use a set of standard map registers take the 
following steps to make the calculation: 


1 Write the byte-offset-in-page field of the UCB (UCBSW_BOFF) into bits 0 
through 8 of a general register. 


2 Get the number of the starting map register for the transfer from CRB$L_ 
INTD+VEC$W_MAPREG. Write bits 0 through 6 of this 9-bit value into 
bits 9 through 15 of the general register. 


3 Write bits 0 through 15 of the general register into the device’s buffer 
address register. 


4 Write bits 7 and 8 of the map register number, acquired in step 2, into 
the extended memory bits of the appropriate device register (usually the 


control and status register (CSR)).4 


MicroVAX 3600-series and MicroVAX II drivers that use a set of alternate map 
registers perform a similar procedure, as follows: 


1 Write the byte-offset-in-page field of the UCB (UCB$W_BOFF) into bits 0 
through 8 of a general register. 


* One example of a device that does not treat the extended memory bits in this fashion is the DRV11-WA, the 
code for which is listed in Appendix F. For the DRV11-WA, code in XADRIVER stores bits 7 and 8 of the map 
register number in a discrete device bus address extension register, then clears the extended address bits of the 
device’s CSR. In contrast, XADRIVER handles the DR11-W according to the method described previously. 
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2 Get the number of the starting alternate map register for the transfer from 
CRB$L_INTD+VEC$W_MAPALT. Write bits 0 through 6 of this 13-bit 
value into bits 9 through 15 of the general register. 


3 Write bits 0 through 15 of the general register into the device’s buffer 
address register. 


4 Write bits 7 through 12 of the map register number, acquired in step 2, 
into the extended memory bits of the appropriate device register (usually 
the control and status register (CSR)). 


12.2.5 Computing the Transfer Length 


Generally, a device driver must indicate to the device the size of a DMA 
transfer by writing to a device register. If a device expects the transfer size 
as a word count, for instance, the start-I/O routine computes the length of 
the transfer in words by dividing the byte count field of the UCB (UCBSW_ 
BCNT) by 2. The routine loads the computed value into the device’s word- 
count register. One of the FDT routines that processes the I/O request must 
ensure that the byte count for the transfer is even. An odd byte count results 
in the user’s not receiving the last byte of data. 


12.2.6 Activating the Device 


Because a driver fork process can address device registers as though they were 
any other virtual address, the loading of the device buffer address register and 
CSR are simple procedures. The driver locates the CSR address of the device 
in the interrupt dispatch block (IDB), as follows: 


UCB — CRB — IDB — CSR address 


The CSR address is the virtual address of a device register. All other device 
registers are located at constant offsets from the CSR address. If, for example, 
the CSR is the first device register and the device’s word-count register is the 
third device register, the device driver can describe the device register offsets 
and load the word-count register with the following series of instructions: 


DEV_CSR = 0 
DEV_XREG = 2 
DEV_WDCNT = 4 


; Compute word count of transfer and store it in user-defined UCB field, 
; UCB$W_WDCNT. 


MOVL UCB$L_CRB(R5) , R4 ;Address of CRB 
MOVL @CRB$L_INTD+VEC$L_IDB(R4) ,R4 ;Address of CSR 
MOVW UCB$W_WDCNT, DEV_WDCNT (R4) ;Move word count to device 


;word count register 


12-23 


UNIBUS and Q22 Bus Device Support 
12.2 Writing Driver Code for UNIBUS/Q22 Bus DMA Transfers — 


12.2.7 Completing a DMA Transfer 


12-24 


12.2.7.1 


After a UNIBUS, MicroVAX 3600-series, MicroVAX II, or MicroVAX I device 
driver fork process activates a DMA device, the driver waits for a device 
interrupt by invoking a VMS macro that suspends execution of the driver. 
When the device requests a hardware interrupt, the interrupt dispatcher gains 
control. | 


The dispatcher saves RO through R5 and transfers control to the driver’s 
interrupt service routine. If the interrupt service routine can match the 
interrupt with a suspended driver fork process, it reactivates the driver 
fork process at the point where execution was suspended. Most driver fork 
processes almost immediately invoke the VMS macro IOFORK. 


IOFORK calls the VMS routine EXE$IOFORK. EXE$IOFORK saves the driver 
context (R3, R4, and PC) in the UCB fork block and inserts the address of 
the fork block (R5) in the processor-specific fork queue corresponding to the 
device’s fork IPL. EXE$IOFORK then returns control to the driver’s interrupt 
service routine, which dismisses the interrupt. 


When the fork dispatcher reactivates the driver fork process, the driver 
performs any necessary cleanup operations, such as purging the data path 
and deallocating adapter resources used in the DMA transfer. 


Purging the Data Path 

Driver fork processes must purge the data path after the DMA transfer is 
complete. This is true for devices with buffered data paths, direct data paths, 
or no data path. 


To purge the data path, the driver invokes the macro PURDPR, which in turn 
calls the VMS routine IOC6PURGDATAP. This routine takes the following 
steps to purge the data path: 


1. Saves the contents of R4 on the stack. 
2  Locates the CRB as follows: 
R5 — UCB — CRB 


3 Obtains the starting address of the UNIBUS adapter’s register space and 
stores it in R2. 


4 Extracts the number of the data path to be purged from the CRB and 
loads it into R1. 


5 Stores the address of the data path register in R4. 


6 Instructs the UNIBUS adapter or Q22 bus interface to purge the data 
path. The routine then modifies RO through R2 to contain the following 
information: 


RO Success/failure status. If the purge completes without error, the routine 
sets SS$_NORMAL in this register. If a data-path error does occur, RO 
is clear and the hardware is reset. 

R1 Contents of the data-path register. 


R2 Address of the first adapter map register. 


The address of the CRB remains in R3. This address, along with the 
information in R1 and R2, is used as input to the error logging routine in 
the event of a data-path error. 
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12.2.7.2 


12.2.7.3 


7 Restores the information stored on the stack to R4 and returns to the 
address in the driver immediately after the invocation of the PURDPR 
macro. 


8 Some machine implementations also check for memory errors that might 
have occurred during the DMA operation, and, if an error is detected, log 
it. 


If a data-path error occurs during a data-path purge, the driver should retry 
the entire DMA transfer. 


Releasing a Buffered Data Path 

A driver fork process releases a buffered data Bath by invoking the VMS 
macro RELDPR. RELDPR calls a VMS routine, IOC$RELDATAP, that 
determines which data path was assigned to the driver fork process and 
releases the data path to a waiting driver. The driver must be executing at 
fork IPL. 


The data-path number is stored in the CRB. IOC6RELDATAP locates it as 
follows: 


UCB — CRB — number of the data path 


If the data path is permanently assigned to a device, IOC6RELDATAP 

does not release the data path. Otherwise, the data path number in the 
CRB (CRB$L_INTD+VEC$B_DATAPATH) is zeroed. The IOC$RELDATAP 
routine attempts to dequeue a waiting driver fork process from the data-path 
wait queue. It finds the queue as follows: 


UCB — CRB — ADP — data-path wait queue 


If another driver is waiting for a buffered data path, IOC$RELDATAP grants 
that driver fork process the data path, restores its context from its UCB fork 
block, and transfers control to the saved driver PC. When IOC6RELDATAP 
can allocate no more data paths, the routine returns to the driver that released 
the data path. This diversion of driver processing is transparent to the driver 
fork process. 


If the data-path wait queue is empty, IOC$RELDATAP marks the data path 
as available in the ADP and returns control to the driver. 


Releasing Map Registers 

A driver fork process releases a set of map registers by invoking the 

VMS macro RELMPR at fork IPL. RELMPR calls the VMS routine 
IOC$RELMAPREG, which releases map registers in a manner similar to 
the way in which the RELDPR macro releases data paths. The CRB records 
the number of map registers assigned to the device. The number of the first 
map register and the number of map registers are located as follows: 


UCB — CRB — number of the first map register 

UCB — CRB — number of allocated map registers 
IOC$RELMAPREG releases the map registers by adjusting the map-register- 
allocation information in the ADP. 


Then, IOC$6RELMAPREG attempts to dequeue a driver fork process from 
the standard-map-register wait queue. If a suspended driver is found, 
IOC$RELMAPREG takes the following steps: 


1 Dequeues the fork block and restores driver context 
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2  Satisfies the map-register request, if possible 


3  Reactivates the driver fork process at the instruction following the driver's 
request for map registers 


4 Repeats steps 1 through 3 


If the standard-map-register wait queue is empty or if IOC6RELMAPREG 

still does not have enough contiguous map registers for any of the waiting 
fork processes, it returns control to the fork process that released the map 

registers. 


VMS supplies a similar macro (RELALT) and routine IOC$RELALTMAP) 
that MicroVAX 3600-series and MicroVAX II drivers can use to release a 

set of alternate map registers (registers 496 through 8191). RELALT and 
IOC$RELALTMAP perform the release in the same manner as RELMPR and 
IOC$RELMAPREG. Note that VMS records the allocation of standard and 
alternate map registers in separate areas of the ADP and CRB. 


12.2.8 Considerations for MicroVAX | DMA Devices 


12-26 


Because the MicroVAX I does not provide a scatter-gather map, 


- MicroVAX I Q22 bus DMA devices must use a physically contiguous buffer 


in data transfers. Because there is no guarantee that this is the state of the 
user’s buffer, the driver must allocate an intermediate buffer consisting of 

contiguous physical pages. The driver never deallocates this buffer unless 

the driver is being unloaded (by means of SYSGEN’s RELOAD command). 
The best time to allocate such a buffer is during the device's initialization. 

Memory is most likely contiguous at that time. Later it will be much more 
difficult to obtain a buffer that contains physically contiguous pages. 


To be sure that the buffer you allocate to the driver is contiguous, use the 
VMS routine EXE$ALOPHYCNTG, described in Appendix C. The size of the 
buffer will depend on the device’s characteristics and the size of the transfers 
requested on the device. A buffer of four pages is likely to be large enough 
for most disk transfers, for example; but if you have enough memory on your 
system, you might want to make your buffer the size of a disk track in order 
to reduce disk latency. In any event, large transfers to the device must be 
segmented into transfers the size of your intermediate buffer. 


When a user requests a transfer to a MicroVAX I Q22 bus device, the driver 
start-I/O routine copies the data from the user’s buffer into the intermediate, 
physically contiguous buffer by means of the routine IOC6MOVFRUSER, 
described in Appendix C. The driver must ensure that the buffer is word- 
aligned because the MicroVAX I has no byte-offset capability. 


The driver then sets up the device for the DMA transfer: 


1 Determines the 22-bit physical address of the buffer from the system 
virtual address returned by EXESALOPHYCNTG. If it has stored the 
virtual address in CRB$L_AUXSTRUC, the driver can use code similar to 
the following excerpt from DLDRIVER (in Appendix E). 
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MOVL UCB$L_CRB(R5) ,R1 ;Get CRB address 

MOVL CRB$L_AUXSTRUC(R1) ,R2 ;Memory alloc failure during 
; controller initialization? 

BEQL 70$ ;If equal, yes, leave offline 


MOVL R2,UCB$A_DL_BUF _VA(R5) ;Save buffer's virtual address 
EXTZV #VA$V_VPN,#VA$S_VPN,R2,R1;Get virtual page number 


; of buffer 
MOVL G*MMG$GL_SPTBASE, RO ;Get base address of SPTs 
MOVL (RO) [Ri] , RO :Get the PTE contents 
BICL3 #°C<VA$M_BYTE>,R2,R1 ;get buffer offset (BAOO-BAO8) 
ASSUME PTE$S_PFN GE 13 
INSV RO,#9,#13,R1 ;Copy BAO9-BA21 


MOVL R1, UCB$A_DL_BUF_PA(R5) ;Save buffer's physical address 


70$: RSB 


2 Moves the low word (bits 0 to 15) of the buffer physical address into the 
device’s buffer address register. 


3 Moves the extended address bits of the buffer’s physical address into the 
device’s extended address register or the device’s CSR, as required by the 
device. 


4 Activates the device as described in Section 12.2.6. 


5 If the transfer size exceeds the size of the buffer, returns to step 1. 


When a user requests a transfer from a MicroVAX I Q22 bus device, the driver 
moves the data from the device to the intermediate, physically contiguous 
buffer by means of a DMA transfer, then calls IOCSMOVTOUSER (as 
described in Appendix C) to copy the data into the user’s buffer. 


A MicroVAX I driver should complete the transfer as described in 
Section 12.2.7. The driver should call IOC6PURGDATATP in order to detect 
and log any memory errors that might have occurred during the transfer. 


12.3 Interrupt Dispatching in a UNIBUS/Q22 Bus System 


The interrupt dispatcher is a combination of hardware and software that routes 
interrupts from a device on the UNIBUS or Q22 bus to the appropriate device 
driver’s interrupt service routine. Although there are slight differences in 

the implementation of the interrupt dispatcher in different VAX systems, it 
performs the same tasks in any given VAX environment. 


When a processor grants a device interrupt, the processor microcode first 
saves the PC and PSL of the currently executing code on the interrupt stack. 
The device responds to the grant by supplying a device interrupt vector in 
the range of 0 to 777, to the processor. VAX/VMS uses the device interrupt 
vector to locate the correct interrupt transfer vector for the device. The 
interrupt transfer vector structure (VEC) contains a short routine which issues 
a JSB instruction to the device driver’s interrupt service routine. Execution 
continues at the location of the transfer vector. 
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This is a somewhat simplified view of the interrupt dispatcher’s activities. 
Figure 12-5 and Figure 12-6 depict the flow of interrupt dispatching from the 
time that a processor grants the interrupt to the processing of the interrupt 
within a device driver’s interrupt service routine. The following subsections 
provide a more complete description of the role of each component in the 
servicing of device interrupts. 


Figure 12—5 Direct-Vector Interrupt Dispatching 
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Figure 12—6 Non-Direct-Vector Interrupt Dispatching 
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12.3.1 Direct-Vector and Non-Direct-Vector Interrupt Dispatching 


The system control block (SCB) contains the vectors that the VAX architecture 
uses to dispatch all interrupts and exceptions. The size of the SCB is system 
dependent. Page 1, the only SCB page defined by the VAX architecture, 
contains the addresses of software and hardware interrupt service routines 
and exception service routines. 
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Table 12-2 VAX System UNIBUS/Q22 Bus Interrupt Dispatching 


Type of 

Interrupt Location of 
VAX System Dispatching Adapter Dispatch Table 
VAX-11/750, VAX-11/730, MicroVAX 3600 Direct SCB pages 2 and 3 
series, MicroVAX Il, MicroVAX | 
VAX-11/780, VAX-—11/785, VAX 8600, VAX Non-Direct ADP vector-jump table 
8650, VAX 8670 
VAX 8200/8250/8300/8350 Direct SCB page 2' 
VAX 8530/8550/8700/8800/8830/8850 Direct SCB page 2' 
VAX 6200 series Direct SCB page 2' 


1Subsequent pages may be used if there is more than one DWBUA in the system. 


The SCB therefore has an initial, albeit system-dependent role, in servicing 
device interrupts. A UNIBUS/Q22 bus system employs either of two methods 
to dispatch a device interrupt (see Table 12-2): 


e If the system in question is a MicroVAX 3600 series, MicroVAX IL, 
or MicroVAX I—or uses a direct-vector UNIBUS adapter (UBA)— it 
dispatches a device interrupt directly through page 2 (or subsequent 
pages, for VAX systems with more than one such UNIBUS) of the SCB. 
It takes the device interrupt vector and uses it as an index into the 
appropriate SCB page, thus obtaining the address of the appropriate 
interrupt transfer vector structure (VEC) for the device. This process is 
known as direct-vector interrupt dispatching. 


e Ina VAX system that employs a non-direct-vector UNIBUS adapter, the 
adapter posts an interrupt that is dispatched through a vector in page 
1 of the SCB that points to a UBA interrupt service routine. For each 
non-direct-vector UBA adapter, the VMS adapter initialization procedure 
creates four such interrupt service routines, each corresponding to a 
device BR (bus request) level, and places them in an area of nonpaged 
pool specially allocated at the end of the adapter control block. 


The UNIBUS adapter’s interrupt service routine performs the following 
actions: 


1 Saves RO through R5 on the interrupt stack. 


2 Reads the UNIBUS adapter’s Bus Request Receive Vector register 
(BRRVR) to determine the vector address of the device requesting the 
interrupt. 


3 Uses the vector address as an index into the adapter dispatch table to 
locate the interrupt transfer vector for the device in the CRB. For each 
non-direct-vector UBA, an adapter dispatch table (also known as the 
vector-jump table) is located after the UBA interrupt service routines 
in nonpaged pool. 


4 Transfers control by means of a JMP instruction to a location within 
the interrupt transfer routine contained in the VEC structure. This 
process is known as non-direct-vector interrupt dispatching. 
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From another point of view, direct-vector interrupt dispatching and non- 
direct-vector interrupt dispatching are characterized by the following two 
factors: 


© — Location of the adapter dispatch table 


e¢ Contents of the interrupt transfer routine 


The following sections further examine the differences in the dispatching 
methods. Figure 12-5 and Figure 12-6 present the flow of tasks performed 
within the context of both direct-vector and non-direct-vector interrupt 
dispatching. 


12.3.2 Adapter Dispatch Table 


The adapter dispatch table contains 128 longword vectors, each of which 
corresponds to a device interrupt vector. Each longword vector within the 
adapter dispatch table contains either the address of an interrupt transfer 
vector structure (VEC), located within the channel request block (CRB) of 
the device’s controller or, if no device is using the vector, the address of the 
adapter’s unexpected interrupt service routine. In either case, the address 
contained in the adapter dispatch table is longword aligned. 


The location of the adapter dispatch table, as signified by the contents of 
ADP$L_VECTOR, is system dependent: 


e The MicroVAX 3600 series, MicroVAX II, MicroVAX I, and those VAX 
systems that employ direct vector UNIBUS adapters situate the adapter 
dispatch table in the second and subsequent pages of the system control 
block (SCB), as described previously. 


¢ Those VAX systems that employ non-direct-vector interrupt dispatching 
situate the adapter dispatch table in a region of nonpaged pool (known 
also as the vector-jump table and commonly referred to as VECTAB). 


12.3.3 Interrupt Transfer Vector and Interrupt Transfer Routine 


The interrupt transfer vector data structure (VEC) is located within the channel 
request block (CRB) corresponding to the interrupting device’s controller, as 
shown in Figure 12-7. 


The interrupt transfer vector structure (see Figures 12-8 and A-7) starts with 
several lines of executable code known as the interrupt transfer routine. 

It also stores several pieces of data, including pointers to the unit and 
controller initialization routines in the device driver, the address of the 
interrupt dispatch block (IDB), and the address of the adapter control block 
(ADP). The interrupt transfer vector may also include information reflecting 
the disposition of the adapter’s map registers. 
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Figure 12—7 VEC Structures Within a CRB 
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There may be one or more interrupt transfer vectors within a single CRB, 
as shown in Figure 12-7. VMS creates the appropriate number of interrupt 
transfer vector structures within a CRB according the the value specified in 
the /NUMVEC qualifier to the SYSGEN command CONNECT. The default 
value is 1. 


VMS automatically initializes the interrupt dispatching instructions and the 
data structure locations in each of the specified vectors. 


The interrupt transfer routine is a piece of executable code at the beginning 

of each interrupt transfer vector. It is the interrupt transfer routine that 
ultimately transfers control to the device driver’s interrupt service routine and, 
to a certain extent, establishes the context for its execution. 


For those VAX systems employing non-direct-vector interrupt dispatching, the 
interrupt transfer routine consists of only one instruction: 


JSB @#“driver-isr-address 


For those VAX systems employing direct-vector interrupt dispatching, the 
interrupt transfer routine consists of the following two instructions: 


PUSHR #°M<RO,R1,R2,R3,R4,R5> 
JSB @#°driver-isr-address 


Note: If the VAX system is a MicroVAX 3600-series or MicroVAX II system with 
multilevel device interrupt dispatching enabled, these two instructions 
are preceded by some instructions that check the legality of the Q22 
bus configuration and conditionally lower IPL. See Section 12.3.4 for a 
description of this optional function of the interrupt transfer routine. 
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Figure 12-8 Interrupt Transfer Vector Block (VEC) 
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The driver-loading procedure obtains the address of the interrupt service 
routine for each interrupt transfer vector structure from the reinitialization 
portion of the driver prologue table (see Section 6.1). This section of the DPT 
contains one or more DPT_STORE macros that identify the addresses of the 
interrupt service routines. For example: 
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DPT_STORE ,CRB,CRB$L_INTD+VEC$L_ISR,D,isr_for_ist_vector 
DPT_STORE,CRB,CRB$L_INTD2+VEC$L_ISR,D,isr_for_2nd_vector 
DPT_STORE, CRB, CRB$L_INTD+ (2*VEC$K_LENGTH)+VEC$L_ISR,D,isr_for_3rd_vector 


The number of DPT_STORE macros that identify interrupt service routines 
must equal the number of vectors given in the /NUMVEC qualifier to the 
SYSGEN command CONNECT to avoid errors in device initialization or 
interrupt handling. 


Immediately following the interrupt transfer routine in the CRB is the address 
of the interrupt dispatch block (IDB) associated with the CRB. When the JSB 
instruction executes, a pointer to the address of the IDB is pushed onto the 
top of the stack as though it were a return address. The driver interrupt 
service routine can use this IDB address as a pointer into the I/O database. 
See Figure 12-5 and Figure 12-6 for an illustration of the context available to 
a driver’s interrupt service routine when it is called by the interrupt transfer 
routine. 
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12.3.4 Multilevel Device Interrupt Dispatching for Q22 Bus Devices 


VAX peripheral devices request interrupts at IPLs 20 through 23. IPLs 20 
through 23 generally correspond with the four bus request levels of the 
UNIBUS (BR4 through BR7) and Q22 bus (BIRQ4 through BIRQ7). 


The UNIBUS also has four bus grant lines (BG4 through BG7). Because 

of this, interrupt dispatching for UNIBUS devices inherently occurs at four 
levels. When a UNIBUS device requests an interrupt at BR4, for example, 
from a processor executing at an IPL lower than IPL 20, the processor grants 
the interrupt to the device at IPL 20 (BG4). If the processor is already 
executing at IPL 20 or above, the device interrupt remains pending. 


The MicroVAX 3600-series and MicroVAX II Q22 bus architecture has but 
one bus grant line (BIAK). As a result, the central processor must, by default, 
grant all Q22 bus device interrupts at a single IPL (IPL 23), even though it 
arbitrates interrupt requests according to the bus request line used. When a 
Q22 bus device requests an interrupt at BIRQ4, for example, from a processor 
executing at an IPL lower than IPL 20, the processor grants the interrupt, 
unconditionally raising IPL to IPL 23. If the processor is already executing at 
IPL 20 or above, the interrupt remains pending. 


There are certain consequences of this implementation of interrupt 
dispatching on the configuration and behavior of Q22 bus devices: ~ 


1 Because the MicroVAX 3600 series and MicroVAX II dispatch Q22 bus 
interrupts at a single IPL, it is essential that Q22 bus devices that request 
interrupts at a high BIRQ be positioned on the bus closer to the CPU than 
devices that interrupt at a low BIRQ. (To determine the BIRQ level of any 
given Q22 bus device, refer to its hardware user’s guide.) 


2 It is possible for a Q22 bus peripheral that requests interrupts at a low 
BIRQ to block the granting of an interrupt to a peripheral that requests 
interrupts at a higher BIRQ. For instance, the processor could grant an 
interrupt to a BIRQ4 device, elevating its IPL to IPL 23 in the process. 
While executing at IPL 23, the processor would not grant the interrupt 
request of a BIRQ7 device. In a real-time environment, where I/O 
operations to one peripheral must always have priority over lesser forms 
of I/O, this behavior can cause problems. 


VMS incorporates a means by which system programmers, concerned about 
real-time performance issues, can avoid these problems and implement 
multilevel interrupt dispatching for devices on a MicroVAX 3600-series and 
MicroVAX II system. 


The default behavior of a MicroVAX 3600-series or MicroVAX II interrupt 
dispatcher is sufficient for a typical MicroVAX 3600-series or 

MicroVAX II system. Only system managers and system programmers 
involved in real-time system environments should attempt to use the 
multilevel device interrupt dispatching capability of VMS Version 5.0. 

Such users should possess a thorough understanding of the VMS interrupt 
dispatching mechanism and the means by which VMS synchronizes access to 
structures in the I/O database. 


If you must enforce real-time device priorities in your Q22 bus system, you 
can do so by setting the QBUS_MULT_INTR system parameter. This static 
parameter causes VMS to set up the proper code and data structures to enable 
multilevel device interrupt dispatching at system initialization.° 


> Other VAX systems ignore the QBUS_MULT_INTR system parameter. 
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When you bootstrap a MicroVAX 3600-series system or MicroVAX II system 
with the QBUS_MULT_INITR system parameter set, VMS initializes data 
structures for each device and implements multilevel device interrupts as 
follows: 


¢ Locates the address of the device driver’s interrupt service routine in the 
driver’s DPT and stores it in the appropriate VEC data structure. 


e Adjusts the corresponding vectors in the second page of the SCB so 
that they point to the multilevel device interrupt dispatching code in the 
interrupt transfer vector (that is, replacing the address of CRB$L_INTD 
with CRB$L_INTD+VEC$L_RTINTD). 


¢ Sets up data and code at VEC$L_RTINTD in the first interrupt transfer 
vector for the device. This code performs special checks for the legality of 
the Q22 bus configuration and conditionally lowers IPL, when necessary, 
to service the interrupts of low priority devices. 


When multilevel device interrupt dispatching is enabled, interrupt dispatching 
proceeds as in the default case. However, after the processor raises IPL 

to IPL 23 to grant the interrupt, the dispatching of the interrupt results in 
the lowering of IPL to device IPL, if necessary, to service the interrupt. 

As a result, the processor, executing at the lower IPL, will be free to grant 
interrupts from higher priority devices. 


Prior to implementing this feature in a MicroVAX 3600-series system or 
MicroVAX II system, users should perform the following tasks: 


1 Ensure that the Q22 bus is properly configured. 


2 Adapt any existing non-DIGITAL-supplied device driver so that it 
correctly initializes any secondary vector (VEC) structures it uses and 
also refers to fields in the channel request block (CRB) and VEC by the 
proper symbolic offsets. 


Ensuring That the Q22 Bus Is Properly Configured 

The MicroVAX 3600-series and MicroVAX II Q22 bus architecture mandates 
that devices with the ability to interrupt at a high BIRQ level (for instance, 
BIRQ7) must be positioned on the bus closer to the CPU than devices that 
interrupt at lower BIRQ levels. In a Q22 bus system, when the processor 
grants an interrupt to a device, the processor passes the interrupt down the 
BIAK line to the first device on the bus. If the device is not the one requesting 
an interrupt, it is responsible for propagating the acknowledgment grant to 
the next device on the bus, and so on. However, if a device coincidentally 
initiates an interrupt just before it would be required to pass the grant further 
down the bus, it may instead “steal” the grant for itself. 


The problems of an illegally configured Q22 bus can be illustrated in the 
following two examples. 


Consider the case of a device that interrupts at BIRQ6 (IPL 22). Assume 

the CPU is at IPL 21. The bus arbitrator will grant the device its interrupt 
and send the grant down the Q22 bus. However, if at this precise moment 

a device that is closer to the CPU on the grant path, and that interrupts 

at BIRQ5 (IPL 21), initiates an interrupt, it may not propagate the grant as it 
should. Instead, it may steal the grant and assume ownership of the interrupt. 
Thus, there exists the possibility of an IPL 21 device successfully interrupting 
a processor executing at IPL 21. The end result is an unpredictable break in 
synchronization that could have a multitude of consequences. 
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Consider also an instance where the second device interrupts at a lower IPL, 
such as BIRQ4 (IPL 20). Although it essentially is executing below the IPL of 
the CPU (IPL 21), this device, too, may steal the interrupt grant. The break in 
synchronization in this instance will result in a reserved operand fault when 
the driver’s interrupt service routine issues the REI instruction, as the VAX 
architecture does not permit an REI from a lower IPL to a higher IPL. 


If the MicroVAX 3600-series system or MicroVAX II system employs the 
multilevel device interrupt dispatching option, VMS introduces special code 
in the interrupt transfer vector data structure that helps prevent violations 
of system synchronization resulting from an illegally configured Q22 bus 
(see Figure 12-8). This code, located at offset VEC$L_RTINTD, checks the 
device IPL of the interrupting peripheral against the IPL in the processor 
status longword (PSL) of the interrupted thread of code. If the device IPL is 
not greater than the IPL in the saved PSL, VMS generates an ILLQBUSCFG 
bugcheck, signifying that the Q22 bus is illegally configured. 


Effects of Enabling Multilevel Device Interrupt Dispatching on Device 
Drivers 

Before enabling multilevel device interrupts in a MicroVAX 3600-series system 
or MicroVAX II system, you should first ensure that all existing device drivers 
have been adapted according to the following guidelines: 


e If the driver creates or accesses any secondary VEC data structures, it 
must take steps to initialize properly the multilevel device interrupt 
dispatching code (at offset VEC$L_RTINTD in the primary VEC 
structure) in these secondary structures. Failure to properly initialize 
these structures in the system can negate any performance increases 
expected as a result of enabling multilevel device interrupt dispatching. 


e The device IPLs of certain Q22 bus devices may differ from those of 
corresponding UNIBUS devices. To ensure that the DPT specifies the 
correct device IPL, refer to the device’s hardware user’s guide. 


e Wherever the driver implicitly refers to the longword in the VEC structure 
that contains the address of the interrupt service routine, it should 
explicitly use the symbol VEC$L_ISR. For example, you should replace 
any instance of CRB$L_INTD+4 with CRB$L_INTD+VEC$L _ISR. 


e If the driver assumes that the contents of the device’s SCB vector (that 
is, the vector in the adapter dispatch table) always points to CRB$L_ 
INTD, it must be appropriately modified to reflect the implementation of 
multilevel device interrupt dispatching. The transfer vector can legally 
point to any longword-aligned address between CRB$L_INTD+VEC$L_ 
RTINTD and CRB$L_INTD+VEC$L_INTD. Because the MicroVAX 3600 
series and MicroVAX II utilize direct-vector interrupt dispatching, the 
transfer vector will never point to VEC$L_INTD+2. 


Although certain of the symbolic offsets defined in the data structure 
definition macro $VECDEF have negative values, driver code can uniformly 
refer to the contents of the VEC structure in the form CRB$L_INTD+VEC$x_ 
symbol. 


1 3 MASSBUS Device Support 


The MASSBUS adapter (MBA) is the hardware interface between the 
backplane interconnect and MASSBUS storage devices. The MASSBUS is 
the communication path linking the MASSBUS adapter to the mass storage 
devices. 


The MASSBUS adapter performs the following functions that allow 
communication between devices and memory: 


¢ Mapping of virtual addresses to physical addresses 
e Buffering of data for transfers between main memory and the MASSBUS 


e Transfer of interrupts from MASSBUS devices to the backplane 
interconnect 


A MASSBUS adapter supports any combination of up to eight device 
controllers. Typical MASSBUS controllers include the TM03 tape controller 
and the RP06, RMO3, and RM80 disk controllers. Only one controller can 
transfer data over the MASSBUS at a time. 


The TM03 tape controller supports up to eight tape drives. In contrast to tape 
controllers, there is a one-to-one relationship between a disk controller and 
its device; each controller supports only one disk drive. The VMS system 
interprets and maintains the I/O database differently, depending upon 
whether the controller is single or multiunit. 


Each MASSBUS controller connected to a MASSBUS adapter is assigned a 
unit number in the range 0 to 7. The method of unit number assignment 

is controller specific, but you can obtain the number from either unit plugs 
or switch packs. In the case of a controller for several devices, the unit 
number is distinct from the subunit numbers assigned to the individual drives 
connected to the controller. 


Figure 13-1 illustrates a possible MASSBUS configuration. 





13.1 MASSBUS Adapter Registers 
The MASSBUS adapter has three sets of registers: 
e The MASSBUS adapter’s registers 
e External registers for each device (controller) on the MASSBUS 


e¢ 256 map registers 


To allow competing devices to share these resources, access to and 
modification of all MASSBUS adapter registers (internal, external, and map 
registers) are governed by certain rules and conventions. In particular, access 
to registers might, at times, require ownership of either the device controller 
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Figure 13-1 MASSBUS Configuration 
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Figure 13-2 MASSBUS External-Register Longword 
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or the MASSBUS adapter itself, or both. Subsequent sections in this chapter 
discuss the methods of obtaining such ownership of these shared resources. 


MASSBUS adapter external registers are device dependent and accessible’ 
whether or not the driver owns the MASSBUS adapter. However, in the case 
of multiinit MASSBUS adapter controllers, the driver might need to own the 
controller before it can gain access to a register. 


MASSBUS adapter external registers are each 16 bits wide, but they must 

be accessed as longwords. When a driver reads an external register, the 
MASSBUS adapter concatenates the high-order 16 bits of the MBA’s status _ 
register (one of the MBA’s internal registers) with the contents of the specified 
external register. Figure 13-2 illustrates the resulting longword. 


On a write to an external register, the MASSBUS adapter uses the low-order 
16 bits of the longword source operand to update the external register. — 


MASSBUS adapter internal and map registers are 32 bits in length. They 
must be accessed as longwords or the processor will signal a machine 
check exception. The driver for a MASSBUS device must obtain exclusive 
ownership of the MASSBUS adapter before modifying any of the MBA’s 
internal or map registers. 
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Bits 21 through 30 of each of the MBA’s map registers are reserved; they 
cannot be written. Use of the MBA’s map registers is analogous to use of the 
UNIBUS adapter’s map registers with the following exceptions: 


¢ Because the MASSBUS can handle only one transfer at a time, ownership 
of the MASSBUS adapter implies ownership of all its map registers. Thus, 
the driver need not independently request map registers. 


e The MBA's map registers do not contain a byte-offset field. The driver 
loads the full MASSBUS adapter virtual address, including the byte 
alignment, into the MASSBUS adapter virtual address register (MBA$L — 
VAR, one of the MBA’s internal registers) at the start of a data transfer. 
Use of the MBA$L_VAR register is described in Section 13.1.1. 


e The MBA’s map registers do not contain a data path field; the MASSBUS 
adapter has a single data path, and ownership of the adapter implies 
ownership of the path. Thus, the driver need not allocate the data path 
independently. 


13.1.1 Loading MASSBUS Adapter Registers 


To prepare for a data transfer over the MASSBUS, the driver that owns 

the MASSBUS adapter uses the LOADMBA macro to load the MBA’s map 
registers and associated internal registers. The LOADMBA macro invokes the 
subroutine IOC6LOADMBAMAP, which performs the following steps: 


¢ Determines the number of map registers needed to map the data area by 
adding the contents of UCB$W_BCNT to UCBSW_BOFF, adjusting the 
sum to the next even multiple of 512, and dividing the result by 512. 


¢ Loads the specified number of map registers, beginning with map register 
0, with the contents of the page-table entries to which 
UCB$L_SVAPTE points. This step maps the data area for the transfer 
into the low portion of the MBA’s virtual address space. The routine also 
loads the next map register beyond the number used to map the data 
area with zeros (an invalid map entry). This procedure stops the transfer 
should a hardware failure occur. 


e Loads the MBA$L_VAR register with the zero-extended contents of 
UCB$W_BOFF. Because the first byte of the data area is located at offset 
UCB$W_BOFF within the page of memory mapped by map register 0, the 
UCB$W_BOFF contains the virtual address of the start of the data area in 
MASSBUS adapter virtual address space. 


¢ Loads the complement (negative) of UCB$W_BCNT into the MBA’s 
byte-count register (MBA$L BCR). 


Note that if a driver is to perform a data transfer in the reverse direction (for 
example, read reverse on a tape), it must modify the contents of the 
MBA$L_VAR, as established by IOCSLOADMBAMAP, so that it points 

to the last byte of the data area. This is done by adding one less than the 
contents of UCB$W_BCNT to the contents of the MBA$L_VAR register. 


During the progress of a data transfer over the MASSBUS, the MBA$L_VAR 
register is continuously updated so that it points to the current position in 
the data area. The VAX Hardware Handbook illustrates the mapping of the 
contents of the MBA$L_VAR register into physical memory. 
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13.1.2 MASSBUS Adapter Registers and Offsets 
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During system initialization, VMS builds an adapter control block (ADP), 

a channel request block (CRB), and an interrupt dispatch block (IDB) for 
each MASSBUS adapter. The system also allocates 4KB of system virtual 
address space for the adapter’s register I/O space. The base of this I/O 
register virtual address space is placed in IDB$L_CSR. Thus, you can access 
MASSBUS adapter registers using the base register virtual address plus 
some offset. The $MBADEF macro defines the offsets for MASSBUS adapter 
registers. The major symbols defined by this macro are shown in Table 13-1. 


Table 13-1 Major Offsets Defined by $MBADEF 


Symbol MBA Register Name Hex Offset 
MBA$L_CSR Configuration register 0 
MBA$L_CR Control register 4 
MBA$L_SR Status register 8 
MBA$L_VAR Virtual-address register C 
MBA$L_BCR Byte-count register 10 
MBA$L_DR Diagnostic register 14 
MBA$L_SMR Selected map register 18 
MBAS$L_CAR Command-address register 16 
MBAS$L_ERB External register base 400 
MBA$L_AS Attention-summary register 414 
MBA$L_MAP Base of map registers 800 


The MASSBUS adapter’s internal registers occupy the low-order 1024 bytes 
of address space even though there are only eight internal MBA registers. 
Beyond the internal registers, there are eight blocks of 32 longwords (128 
bytes) each, one block for each of the eight device controllers that can be 
connected to a single MASSBUS adapter. Each of these blocks provides space 
for the device registers of each controller. Beyond the device-register space is 
the area reserved for the MASSBUS adapter’s 256 map registers. 


Figure 13-3 illustrates the relative positions of the MASSBUS adapter’s 
registers and the values device drivers use to gain access to them. The base 
address of the MASSBUS adapter’s address space, stored in IDB$L_CSR, is 
the address of the first of the MASSBUS adapter’s internal registers. 
IDB$L_CSR represents the internal register’s virtual location, while the 
MBAS$L__ symbols represent register values as defined by $MBADEF. Note 
that the MASSBUS adapter’s register space occupies only the first 3KB out 
of the 8KB allotted to physical I/O address space. However, by convention, 
VMS allocates 4KB of virtual addresses to each MASSBUS adapter. 


To address a map register in the MASSBUS adapter, the driver constructs the 
following address: 


IDB$L_CSR + MBA$L_MAP + map-register-index 
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Figure 13-3 Location of MASSBUS Registers in Physical Address 
Space 
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An individual driver should define offsets for the registers of its device. 
During execution, the driver computes a register address by summing the 
MBA’s starting virtual address (the contents of IDB$L_CSR), MBA$L_ERB, 
the unit number of the device controller multiplied by 8016, and the offset of 
the specified register. 


The attention-summary register (MBA$L_—AS), as shown in Table 13-1, 
appears to reside within the external-register space reserved for MASSBUS 
adapter controller 0. Actually, the attention-summary register is a composite 
register. Each of the MASSBUS adapter’s controllers contributes one bit of 
information to the register. This composite register appears in each of the 
eight device register spaces at offset 10), from the base of the device registers 
for that device. Thus, MBA$L_AS can be defined as any of the values 4104¢, 
49016, 51016, 590;¢, and so on. For convenience, it has been defined as 


41016. 
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13.1.3 Modifying MASSBUS Adapter Registers 


The driver for a MASSBUS device must obtain ownership of the MBA before 
Aenoaitvine any of the MBA’s internal registers or map registers. A driver 
obtains ownership of the MBA by invoking either the REQPCHAN macro or 
the REQSCHAN macro, depending on whether the device is connected to a 
single-unit MASSBUS controller or a multiunit MASSBUS controller. 


For dedicated controllers, invoke the REQPCHAN macro. Because the 
controller is dedicated to its single device, there is never any contention 
for the controller. 


For multiunit devices, however, invoke the REQSCHAN macro to obtain 
MBA ownership because several devices can share the controller, and so must 
contend for its use. The controller for several devices relegates the MASSBUS 
adapter to a secondary position. Thus, for multiunit controllers, invoke 
REQPCHAN to gain ownership of the controller, and invoke REQSCHAN to 
obtain the MASSBUS adapter. 


13.2 I/O Database for MASSBUS Devices 
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During initialization, the system creates an ADP, a CRB, and an IDB for 
each MASSBUS adapter included in the configuration. The driver-loading 
procedure subsequently builds additional data structures for each device 
controller connected to a MASSBUS adapter. The type of structure created 
depends upon whether the device controller is a dedicated controller or the 
controller of several devices. 


The system builds a unit control block (UCB) for each single-unit controller. 
Figure 13-4 illustrates the I/O database for a MASSBUS adapter with one 
dedicated controller attached to it. Note that the ADP, CRB, and IDB all 
correspond to the MASSBUS adapter and can logically be considered a single, 
extended data block. The UCB corresponds to the device/controller pair. 
Because of the one-to-one correspondence between a dedicated controller and 
its device, the system does not need to distinguish between the two and thus 


does not maintain separate data blocks for each piece of hardware. 


A controller of several devices, however, requires separate data structures for 
the controller and each of its subunits (devices). The driver-loading procedure 
builds a CRB/IDB pair for the controller, as well as a UCB for each subunit. 
Figure 13-5 shows the I/O database created for a MASSBUS adapter with 
one disk unit and two tape units. 


Figure 13-5 does not include several pointers used in interrupt dispatching. 
In particular, the IDB associated with the MASSBUS adapter maintains an 
array of up to eight longwords that point to the data structures associated 
with the eight possible MASSBUS controllers attached to the MASSBUS. 


For dedicated controllers, the IDB longword points to the device’s UCB; 
whereas, for a controller for several devices, the longword (or longwords) 
points to a field within the CRB associated with the controller. The low 

bit of this longword, when set, indicates a multiunit vector. The software 
checks this bit to determine whether the longword points to a single UCB or 
a multiunit CRB. 
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Figure 13—4 1/O Database for MASSBUS Disk Unit 
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Figure 13-5 1[/O Database for MASSBUS Disk and Tape Units 
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Also not pictured in Figure 13-5 is how multiunit IDBs also maintain an array 
of longwords. Each longword points to the individual UCBs for the units 
attached to the controller. Figure 13-6 illustrates in more detail the set of I/O 
data structures for the MASSBUS adapter and its devices. 
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Figure 13-6 
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The MASSBUS accepts two kinds of operations: data transfer operations 
and nondata transfer operations. Data transfer operations require the use of 
MASSBUS adapter shared resources, while nondata transfers do not. 


Before a driver can activate a data transfer operation on the MASSBUS, the 
driver must request and receive ownership of the MASSBUS adapter on 
behalf of the device unit. However, drivers must not initiate nondata transfer 
operations while they have control of the MASSBUS adapter. Section 13.4.1 
explains this statement further. 


The MASSBUS adapter generates interrupts when data transfers terminate 
and when attention conditions arise on devices. When an interrupt occurs 
on the MASSBUS adapter, the MASSBUS adapter’s interrupt dispatcher 
determines whether the interrupt is for a data transfer or an attention 
condition. | : 


Data transfer interrupts occur when a data transfer either completes or is 
aborted. When the interrupt occurs, the MBA’s status register (MBA$L SR) 
contains information about the condition that caused the interrupt. 
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Attention interrupts occur when nondata transfers on MASSBUS devices 
terminate, or when the device undergoes an exceptional condition, such as 
coming on line. 


The MASSBUS adapter’s attention-summary register controls attention- 
interrupt handling. This register contains eight bits of data, one for each 
of the eight possible controllers that can be connected to the MASSBUS 
adapter. When a device incurs an attention condition, the hardware sets 
the corresponding bit in the attention-summary register and generates a 
MASSBUS adapter interrupt. 


If the attention condition occurs while a data transfer operation for another 
device is in progress, the hardware sets the bit in the attention-summary 
register but suppresses the attention interrupt. The interrupt generated when 
the data transfer is completed allows the MASSBUS adapter’s interrupt 
dispatcher to gain control, handle the data transfer interrupt, check the 
attention-summary register and then invoke the proper driver to handle the 
attention condition. 


13.4  MASSBUS Adapter’s Interrupt Dispatching 


When interrupts occur on the MASSBUS adapter, the MASSBUS adapter’s 
interrupt dispatcher gains control. This routine first determines whether the 
interrupt is the result of a data transfer or an attention condition. The routine 
checks to see if the MASSBUS adapter is owned and, if so, by whom. 


13.4.1 Checking for MASSBUS Adapter Ownership 


There are two conditions by which the interrupt dispatcher can determine 
that the interrupt is an attention interrupt: 


e If the MASSBUS adapter is not owned 


e If the MASSBUS adapter is owned, but the owner is not expecting an 
interrupt (UCB$V_INT in UCB$L_STS is clear) _ 


When the MASSBUS adapter is owned and the owner expects an interrupt, 
the interrupt is assumed to be the result of a data transfer operation. 


As mentioned earlier, a driver must not initiate nondata transfers on the 
MASSBUS adapter while it owns the adapter. For example, consider a 
MASSBUS adapter attached to two disk units, A and B. Disk A is performing 
an IO$_SEEK (a nondata transfer operation that completes fairly quickly), 
while at the same time, disk B is performing an IO$_RECAL operation (a 
nondata transfer operation that takes about 0.5 seconds to complete). 


The driver for disk A correctly initiates its operation without obtaining 
possession of the MASSBUS adapter channel, but the disk B driver 
initiates its operation while it owns the MASSBUS adapter. Both of these 
operations, upon completion, set the bit in the attention-summary register 
that corresponds to their respective drive units, and initiate an interrupt. We 
will assume that disk A’s IO$_SEEK is completed first. The operation sets 
disk A’s bit in the attention-summary register and generates the MASSBUS 
adapter’s interrupt. 
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The MASSBUS adapter’s interrupt dispatcher finds that the adapter is owned, 
and that the owner is expecting an interrupt. Therefore, the interrupt 
dispatcher incorrectly assumes that it is handling a data transfer interrupt, 
and, moreover, that this interrupt is the one for which the owner of the MBA 
is waiting. 


As a result, the MASSBUS adapter’s interrupt dispatcher returns control, 
through the fork block in the MASSBUS adapter owner’s UCB, to the driver 
for disk B, even though disk B’s operation has not completed. The disk 

B driver will now incorrectly assume that the device has completed its 
operation, which can cause serious problems. 


13.4.2 Dispatching a Device Interrupt 
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Once the MASSBUS adapter’s interrupt dispatcher determines the type of 
interrupt, it dispatches the interrupt to the driver. The interrupt dispatcher 
handles attention interrupts and data transfer interrupts in the same way, 
with one exception: on an attention interrupt, the interrupt dispatcher clears 
the MASSBUS adapter’s status register (MBA$L_SR) before dispatching the 
interrupt to the driver. The status register contains information used only in 
data transfer interrupt dispatching. 


How the interrupt dispatcher dispatches the interrupt to the driver differs 
depending on the type of controller. 


The MASSBUS adapter’s interrupt dispatcher handles a solicited interrupt 
on a dedicated controller by transferring control to the driver through the 
fork block in the UCB. On unsolicited interrupts on dedicated controllers, the 
interrupt dispatcher calls the driver’s unsolicited interrupt service routine. 


On dedicated controllers, the MASSBUS adapter’s interrupt dispatcher always 
clears the attention bit in the attention-summary register before it calls back 
the driver after an interrupt. 


Dispatching interrupts to the driver of a device that shares its controller with 
several other devices differs in two ways from dispatching interrupts to the 
driver of a device with a dedicated controller. 


First, the interrupt dispatcher never clears the attention bit. This task is left 
to the driver because some controllers that control more than one device use 
this bit to synchronize their activities, and guarantee the integrity of device 
registers only while the bit is set. If the interrupt dispatcher clears the bit 
before returning control to the driver, the driver can no longer rely on the 
contents of the device's registers. 


Second, a controller that controls several devices needs another interrupt 
dispatcher to handle simultaneous requests from its several subunits. This 
second-level interrupt dispatcher resides in the driver. After an interrupt, the 
MASSBUS adapter’s interrupt dispatcher indirectly calls this second driver’s 
interrupt dispatcher using code in the controller’s CRB. The driver-loading 
procedure installs this code when it establishes the I/O database. 
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13.5 Special Considerations for MASSBUS Device Drivers 


MASSBUS adapter considerations affect a driver’s device unit initialization 
routine, start-I/O routines and, for multiunit controllers only, the driver's 
use of the DPTAB macro. MBA considerations also affect interrupt handling, 
as described in Section 13.4.2. The next sections in this chapter discuss 
programming details for writing a MASSBUS device driver. 


13.5.1 Unit Initialization Routine 


All drivers for MASSBUS adapter devices initialize two fields in the UCB (as 
well as initializing device-specific fields): UCB$B_SLAVE and 
UCB$B_SLAVE+1. The first of these fields should contain the controller’s 
MASSBUS adapter unit number, which marks the controller’s position on the 
MASSBUS adapter. The second of these contains the offset, in longwords, 
from the start of the MASSBUS adapter’s external registers to this controller’s 
device registers. The value of this longword offset is always 32 times the unit 
number of the controller. 


Initialization of a device attached to a dedicated controller is simple because 
the device unit number and the controller position number on the MASSBUS 
adapter are always equal. To initialize the field UCB$B_SLAVE, copy to 

it the contents of UCBSW_UNIT. To initialize UCB$B_SLAVE+1, multiply 
the contents of UCB$W_UNIT by 32. The driver’s fork process or interrupt 
service routine later uses this information to compute a pointer to this device’s 
registers. By convention, R4 points to the MASSBUS adapter configuration 
register, and R5 points to the UCB of this device. 


Thus, the following two instructions cause R3 to point to the device registers 
during normal system operation: 


MOVZBL UCB$B_SLAVE+1(R5) ,R3 
MOVAL MBA$L_ERB(R4) (R3] ,R3 


For devices connected to a controller that controls several devices, 
determination of the controller’s MBA position is more complex. When 
the unit initialization routine is invoked, the following values are in the 
following registers: 


R3 Address of controller's device registers 

R4 Address of the MBA's configuration register 

R5 Address of device’s UCB 

The driver computes the MBA position of the controller by using R3 and 
R4 to determine the number of bytes from the start of the MBA’s external 


registers to the start of the device’s device registers. The difference, when 
divided by 128, is the controller’s MBA position number. 
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13.5.2 The MASSBUS Adapter and the |/O Database 


13.5.3 Start-1/O Routine 
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The UCB of a device connected to a single-unit controller, at offset 
UCB$L_—CRB, contains the address of the MASSBUS adapter’s CRB. This 
CRB in turn contains, at offset CRB$L_INTD+VEC$L _IDB, the address of 
the MASSBUS IDB. This IDB points to the base address of the MASSBUS 
adapter registers at offset IDB$L_—CSR. 


A controller that controls several devices maintains a more complicated I/O 
database. The device UCB, at offset UCB$L—CRB, points to the controller’s 
CRB, and this structure points to the CRB for the MASSBUS adapter at 
offset CRB$L_LINK. Also, the controller’s CRB points to its own IDB at 
offset CRB$L_INTD+VEC$L~_IDB. This IDB points to the controller’s device 
registers at offset IDB$L_CSR. 


Thus, the UCB for a device always points to that device’s primary CRB, 
whether it is the MASSBUS adapter’s CRB or the controller’s CRB. The 
primary CRB points to the secondary CRB, if one exists for the device. 


Figure 13-6 shows these relationships among I/O data structures. 


Depending on the function being executed, the start-I/O routine for a 
MASSBUS device performs all or some of the following tasks: 


¢ Requests, if necessary, controller data channel(s) as described in 
Section 13.5.3.1 


¢ Clears errors on the MASSBUS adapter by placing the value -1 into the 
MBA’s status register; this is a write-ones-to-clear register (MASSBUS 
device registers and the MBA’s registers are all longwords) 


¢ Invokes the LOADMBA macro to load the MBA’s map registers as 
described in Section 13.5.3.2 


¢ Loads device registers to start the function 
¢ Waits for a device interrupt or timeout 


¢ Releases, if necessary, controller data channel(s) as described in 
Section 13.5.3.3 


e Finishes the request like other drivers 


Requesting Controller Data Channels 

Device drivers for MASSBUS devices must request and receive ownership of 
the MASSBUS adapter channel before loading the MBA’s internal registers 
or map registers. In addition, drivers for devices connected to multiunit 
controllers must obtain ownership of the controller channel before modifying 
the contents of controller registers that can be shared among the units 
connected to the controller. 


Drivers for dedicated controllers must request ownership of the MASSBUS 
adapter channel by invoking the macro REQPCHAN. 
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Device drivers for controllers that control several devices invoke the 
REQPCHAN macro when the operation requires ownership of only the 
primary channel (the controller’s channel). However, if the operation 
requires ownership of both primary and secondary channels (a data transfer 
operation), the driver must first obtain the controller channel and then request 
the MASSBUS adapter channel by invoking the REQSCHAN macro. 


Again, the driver needs ownership of both channels only when performing 

a data transfer, and must release the channels before initiating a nondata 
transfer. Thus, a driver must obtain ownership of the MASSBUS adapter 
channel some time before initiating a data transfer and must either not 

own the channel or release such ownership before it invokes the WFIKPCH 
macro, or issue the WFIRLCH macro, following the start of a nondata transfer 
operation. 


Loading Map Registers 

MASSBUS device drivers invoke the LOADMBA macro before they initiate 
a data transfer, to load the MBA’s map registers, the MBA’s virtual-address 
register (MBA$L_VAR), and the MBA’s byte-count register (MBA$L_—BCR). 
Drivers cannot modify these registers during a transfer. The LOADMBA 
macro expects the following register contents: 


e The address of the MBA’s configuration register (MBA$L_—CSR) in R4 
e The address of the device UCB in R5 


LOADMBA preserves the contents of R3 but modifies RO through R2. The 
macro performs the following steps: 


1 Uses the contents of UCB$W_BCNT and UCB$W_BOFF to determine the 
number of pages that contain pieces of the I/O buffer. 


2 Beginning with the page-table entry to which UCB$L_SVAPTE points 
and continuing for the number of page-table entries determined in 
step 1, copies the page-frame numbers from the page-table entries to the 
corresponding map registers, starting at map register 0. 


3 Ensures that the valid bit is clear in the map register that immediately 
follows the last map register loaded with a PFN. This prevents a hardware 
fault or prefetch from modifying memory. 


4 Moves the negative value of the transfer byte count (UCB$W_BCNT) into 
the MBA’s byte-count register (MBA$L_BCR). 


5 Moves the byte offset in the first page of the transfer (UCB$W_BOFF) into 
the MBA’s virtual-address register (MBA$L__VAR). 


6 Returns to the start-I/O routine that invoked it. 


If the I/O operation about to be initiated by the driver is a reverse operation 
(a read-reverse on tape), the driver must modify the contents of the MBA’s 
virtual-address register set up by LOADMBA. Because reverse operations 
access the I/O buffer from its highest address through its lowest address, 
the value to be loaded into the MBA’s virtual-address register must be the 
virtual address, in MBA’s virtual memory, of the last byte of the buffer. This 
number is equal to one less than the sum of the contents of UCB$W_BOFF 
and UCB$W_BCNT. 
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13.5.3.3 


13.5.4 DPTAB Macro 


Releasing Controller Data Channels 

The driver releases the controller data channels by invoking the RELCHAN 
macro. RELCHAN releases all controller channels (both primary and 
secondary) currently owned by the device. To release only the secondary 
channel and retain ownership of the primary channel, a driver can invoke the 
RELSCHAN macro. 


The device driver fora MASSBUS device that shares its controller with other 
devices must set the DPT$V_SUBCNTRL bit in the flags argument of the 
DPTAB macro. Setting this bit causes the driver-loading procedure to create a 
second CRB and an IDB for the controller. 


13.6 Interrupt Service Routines for MASSBUS Devices 


The MASSBUS interrupt dispatcher (MBA$INT) gains control when it receives 
an interrupt from the MASSBUS adapter. Because data transfers in progress 
suppress attention interrupts on the MASSBUS adapter, and because several 
devices can request attention simultaneously, several device drivers might 
need to be informed of the interrupt. 


MBAS$INT determines which drivers should be invoked as a result of the 
interrupt and then passes control to these drivers. For data transfer interrupts, 
MBAGSINT preserves the value contained in the MBA’s status register at the 
time of the interrupt so that the driver can have access to this value. 


For I/O operations that involve no data transfer, MBAS$INT clears this register 
before invoking the driver. MBA$INT only preserves the contents of registers 
R2 through R5. Drivers that use other registers must save the contents of 
those registers, and must restore them before exiting from the interrupt 
service routine. 


13.6.1 Transferring Control to the Interrupt Service Routine 
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The method by which MBASINT invokes a driver depends upon whether 
the driver serves a device connected to a dedicated controller or a device that 
shares its controller with several other devices. Furthermore, if the device is 
connected to a dedicated controller, the method of transfer from MBA$INT to 
the driver depends upon whether or not the interrupt is expected. 


For a device on a dedicated controller whose driver is expecting an interrupt, 
MBASINT restores the driver context saved in the UCB fork block and 
transfers control (using a JSB instruction) to the instruction that follows the 
wait-for-interrupt instruction. 


For a device on a dedicated controller whose driver is not expecting interrupts, 
MBA$INT obtains the address of the driver’s unsolicited interrupt service 
routine from the driver dispatch table and calls the routine. 


For a device that shares its controller with several other devices, MBA$INT 
transfers control to the driver’s interrupt service routine by simulating a 
direct transfer, through an interrupt vector, to the controller’s CRB. The CRB 
contains code that transfers control to the interrupt service routine. 
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MBAS$INT first pushes the processor status longword (PSL) onto the stack. 
The routine then calls (with a JSB instruction that leaves an address within 
MBASINT on the stack) the code within the CRB. This code contains the 
following sequence of instructions, where XX$INT is the address of the 
interrupt service routine and XX$IDB is the address of the controller’s IDB: 


PUSHR #°M<R2,R3,R4,R5> 
JSB XX$INT 
. LONG XX$IDB 


The execution of the previous instruction sequence, plus the instructions 
executed by MBAS$INT (the pushing of the PSL onto the stack and the JSB), 
places a simulated interrupt frame onto the stack, including a saved PSL, a 
saved PC, saved registers, and a pointer to an address in the IDB. 


13.6.2 Returning Control to MBASINT 


The way in which a driver returns control to MBA$INT depends on the way 
in which MBASINT invoked it. Drivers for dedicated controller devices return 
to MBA$INT through an RSB instruction, although the RSB can execute as a 
result of the driver’s invoking the IOFORK macro. 


Drivers of devices that share a controller return control to MBA$INT by 
removing the indirect pointer to the IDB from the top of the stack, restoring 
registers R2 through R5, and executing an REI instruction. This sequence, 
executed within the driver’s interrupt service routine, eliminates the simulated 
interrupt frame from the stack before returning to MBAS$INT. | 


13.6.3 Considerations for Interrupt Service Routines 


Drivers for dedicated controller devices attached to the MASSBUS do not 
have interrupt service routines. Instead, MBA$INT handles all the functions 
that a driver interrupt service routine normally provides. 


Drivers of devices that share a controller on the MASSBUS must have their 
own interrupt service routines. In general, these routines perform the same 
functions as the interrupt service routines for UNIBUS and Q22 bus devices 
(discussed in Chapter 9). However, the two types of drivers diverge in two 
areas. 


One difference between UNIBUS/Q22 bus and MASSBUS drivers concerns 
the number of registers saved by the interrupt service routine. When the 
interrupt dispatcher transfers control to a MASSBUS driver interrupt service 
routine, registers R2 through R5 are pushed onto the stack. UNIBUS/Q22 
bus drivers save RO through R5. 


After handling an interrupt, both MASSBUS and UNIBUS/Q22 bus driver 
interrupt service routines execute an REI instruction. For UNIBUS/Q22 bus 
devices, the REI dismisses a real interrupt, whereas the MASSBUS driver’s 
RE] returns control to MBA$INT. 
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14 Generic VAXBI Device Support 


14.1 


14.2 


This chapter provides information needed to write and load a device driver 
for a non-DIGITAL-supplied device attached to the VAXBI bus. VMS provides 
special support for such devices in the system initialization routines for the 
VAX 8200/8250/8300/8350, VAX 8530/8550/8700/8800/8830/8840, and 
VAX 6200-series systems. Because of the many and varied implementations 
of VAXBI devices, however, VMS support must of necessity be very general. 
Some devices may more fully utilize the VAXBI interface than others; a device 
may incorporate its interface initialization logic in microcode, whereas another 
may defer initialization to code in its driver. 


The VAXBI Options Handbook includes a description and guidelines for 
possible VAXBI device implementations. Refer to that manual for further 
discussion of all VAXBI topics discussed in brief in Section 14.2 and elsewhere 
in this chapter. 





Overview 


A VAXBI device driver refers to the same data structures and contains the 
same routines as a traditional VMS driver. A VAXBI device driver deviates 
from the traditional VMS driver almost exclusively in code that initializes the 
VAXBI interface or supports direct-memory-access (DMA) transfers for devices 
that address memory across the VAXBI bus. Section 14.4 discusses tasks that 
drivers of various VAXBI devices may perform in their initialization routines 
to supplement VMS initialization and that initialization performed by device 
microcode. Section 14.5 contains a general discussion of how some VAXBI 
devices and their drivers manage DMA transactions. 


Section 14.3 describes those data structures the VMS adapter initialization 
routine creates and prepares for a generic VAXBI device, while Section 14.8 
discusses the method by which its driver can be loaded into the operating 
system. The final section of this chapter provides reference material and 
includes a description of the backplane interconnect interface chip (BIIC) 
registers. 





VAXBI Concepts 


The VAXBI serves as the I/O bus for the VAX 8200/8250/8300/8350, 
VAX 8530/8550/8700/8800/8830/8840, and VAX 6200-series systems (see 
Figure 1-3).! The VAX 8200/8250/8300/8350 systems can have a single 
VAXBI; the VAX 8530/8550/8700/8800/8830/8840 and VAX 6200-series 
systems can have multiple VAXBI buses. 


Each location on a VAXBI bus is called a node. A single VAXBI bus can 
service 16 nodes. In the case of the VAX 8200/8250/8300/8350 systems, 
these nodes can be processors, memory, and adapters; the VAX 8530/ 
8550/8700/8800/8830/8840 and VAX 6200-series systems permit only 


" The VAXBI is also the system bus for the VAX 8200/8250/8300/8350 systems. 
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adapters to be attached to the VAXBI bus.” A node receives its node ID, a 
number from 0 to 15, from a plug on the VAXBI backplane slot into which 
the node module is inserted. 


An adapter is a node that connects other buses, communication lines, and 
peripheral devices to the VAXBI bus. This chapter uses the term device to 
refer to a device or combination of devices serviced by a single adapter or 
controller. 


14.2.1 VAXBI Address Space 





Each VAXBI bus supports 30-bit addressing capability. This gigabyte of 
physical address space is split equally between memory and I/O address 
space, as shown in Figure 14-1. 


Figure 14—1 VAXBI! Address Space 


Hex Address 


0000 0000 
Memory Space 
512MB 
2000 0000 
1/O Space 
512MB 
SFFF FFFF 
ZK-5541-86 


All memory locations on a VAXBI bus are addressed using physical addresses 
in VAXBI memory space (from 000000001, through 1FFFFFFF),). A VAXBI 
device that accesses memory directly (or indirectly through a memory- 
interconnect-to-VAXBI adapter), or its driver, must perform virtual-to- 
physical translation before transmitting a memory address on the bus. (See 
Section 14.5 for additional information). 


VAXBI I/O address space (physical addresses 20000000,,¢ through 
3FFFFFFFj¢) is partitioned as illustrated in Figure 14-2. Figure 14-3 shows 
the structure of an I/O-space address. 


? For VAX 8530/8550/8700/8800, VAX 8830/8840, and VAX 6200-series systems, the memory-interconnect-to- 
VAXBI adapter (NBI PBI, or DWMBA) or, more specifically, the NBIB, PBIB or DWMBA/B resides at a node on 
a VAXBI bus, monitoring and controlling transactions to the memory interconnect (NMI, NMIs, or XMI) where 
the processors and memory reside. 
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Figure 14-2 Description of VAXBI I/O Address Space 


Hex Address 


2000 0000 
Node 0 Nodespace 
(8KB) 
2000 1FFF 
2001 E000 
Node 15 Nodespace 
(8KB) 
2001 FFFF 
2002 0000 
Multicast Space 
(128KB) 
2003 FFFF 
2004 0000 
Node Private Space 
- (3.75MB) 
203F FFFF 
Node 0 2040 0000 
Window Space 
ene) 2043 FFFF 
15 207C 0000 
Window Space 
(256KB) 207F FFFF 
RESERVED 
RESERVED 
(for multiple VAXBI systems) 
(480MB) 
SFFF FFFF 





2K-5542-86 
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Figure 14—3 Physical Addresses in VAXBI I/O Address Space 





29 


[‘] (0 SPACE 


28 25 


[| SPECIFIES WHICH VAXBi BUS 


24 23 


IF NOT ZERO BITS <24: 23> INDICATE RESERVED SPACE 


22 
[}] WINDOW SPACE 


21 18 
SPECIFIES WHICH NODE'S WINDOW SPACE 


17 0 





22 
NON-WINDOW SPACE 


21 20 19 18 
0 0 0 0] IF NOT ZERO BITS <21: 18> INDICATE NODE PRIVATE SPACE 


17 
[o] NODESPACE 


16 13 
NODE ID 


12 0 


17 
[‘] MULTICAST SPACE 


16 0 


2K-5543-86 
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As shown in Figures 14-2 and 14-3, VAXBI architecture grants each of the 16 
nodes on a VAXBI bus two discrete sections in I/O address space. 


Node space An 8KB block of addresses consisting of 256 bytes 
of BIIC CSR space, followed by user interface CSR 
space. A device can access the control and status 
registers (CSRs) of its backplane interconnect interface 
chip by using BIIC CSR space addresses. Device-specific 
registers reside in user interface CSR space. | 


Because the VMS adapter initialization routine virtually 
maps node space for each VAXBI node on each VAXBI 
bus, a device driver can access both BIIC registers and 
device registers using virtual addresses. (See Sections 
14.4 and 14.5 for a discussion of driver access to 
registers.) 


Window space A 256KB block used by a VAXBI adapter to map an 
1/O transfer to a target bus. Because VMS does not 
automatically map window space to virtual addresses, 
a driver that manipulates addresses in window space 
must itself allocate and fill sufficient system page-table 
entries for the range of its window space addresses. 
(See Section 14.4.) 


Note that node private space contains locations used for the storage of 
bootstrap firmware and software. VAXBI nodes are not permitted to issue 
or respond to VAXBI transactions targeting locations in node private space. 


14.2.2 Backplane Interconnect Interface Chip (BIIC) 


The backplane interconnect interface chip (BIIC) serves as the primary interface 
between the VAXBI bus and the user interface logic of a node. The BITC 
supplies the logic necessary for a node to initiate and respond to transactions 
on the VAXBI bus, arbitrate bus ownership, send and receive interrupt 
requests, and monitor bus errors. 


A node can enable, control, and monitor such activities by accessing the set 
of BIIC registers located in the first 256 bytes of its node space. Because 

the VMS adapter initialization routine virtually maps node space addresses, 
drivers for VAXBI devices can use virtual addresses to access BIIC registers. 
In addition, given the virtual address of the base of a device’s node space, a 
driver can use the symbolic offsets, masks, and bit fields defined by the VMS 
macro $BIICDEF (in SYS$LIBRARY:LIB.MLB). Table 14-1 describes these 
symbols. 


14.3 = Initialization Performed by VMS 


During the phase of system initialization known as adapter initialization 
VMS performs a set of system-specific tasks to identify and configure each 
device it discovers at each of the 16 nodes on each VAXBI bus in the system 
configuration. 
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> 
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The adapter initialization module configures DIGITAL-supplied and non- 
DIGITAL-supplied devices alike, performing the following activities as part of 
its initialization cycle: 


1. Tests for the presence of a device at the node by issuing a MOVL 
instruction, the target of which is a system virtual address temporarily 
mapped to the first longword of its node space. If this instruction is 
successful, it returns the contents of the BIIC Device Type Register of the 
addressed node to the processor.? 


2 Records the contents of the low 16 bits of the BIIC Device Type Register, 
plus an I/O bus identifier in the slot in the CONFREGL array that 
corresponds to the VAXBI bus and node at which it found the device,* 
and compares this value against a table of recognized device types. 


3 If it recognizes the device, maps the number of pages specified in the 
table for the device type, and places the system virtual address of the 
base of the mapped node space in the slot in the SBICONF array that 
corresponds to the VAXBI bus and node at which it found the device.° 


If it does not recognize the device, maps the entire 8KB of the node’s node 
space into VMS virtual address space by allocating 16 system page-table 
entries (SPTEs) and associating them with the 16 page-frame numbers 
(PFNs) of the physical addresses assigned to this node’s node space on 
this VAXBI bus. The adapter initialization module then saves the base 
system virtual address of the resulting 8KB range in the longword slot 
corresponding to this node in the SBICONF array. 


4 Performs such additional tasks as allocating and filling in data structures 
in a device-specific manner. For a non-DIGITAL-supplied device attached 
to a VAXBI bus, VMS creates generic versions of the channel request 
block, interrupt dispatch block, and adapter control block—and fills in 
the appropriate vectors in the system control block—as discussed in 
Section 14.3.1. 


For devices it does recognize, VMS additionally calls a VMS-supplied 
subroutine, the address of which it obtains from the device-type table, 
that performs further device-specific initialization. 


For devices it does not recognize, VMS must defer device-specific 
initialization to the device driver’s initialization routine. 


If no device exists at a given VAXBI node address, the CPU becomes aware of this in a system-specific 


way. For example, the VAX 8200/8250/8300/8350 systems experience a machine check, whereas the VAX 
8530/8550/8700/8800/8830/8840 and VAX 6200-series systems determine that the node is vacant by reading 
an NXM (nonexistent memory) error from the BIIC Bus Error Register of the NBIB, PBIB, or DWMBA on the 
VAXBI being examined. 

The CONFREGL array is a set of longwords in system pool pointed to by EXE$GL_CONFREGL. The 
CONFREGL array contains an entry for each possible VAXBI node. For VAX 8200/8250/8300/8350 systems, 
with one VAXBI, this array has 16 entries. For VAX 8530/8700/8800/8830/8840 and VAX 6200-series systems, 
this array has 16 entries for each VAXBI bus on the system. 

The SBICONF array is a set of longwords, similar in structure to the CONFREGL array and pointed to by 
MMG$GL_SBICONF, that lists the system virtual addresses of the base of the node space for each node on a 
VAXBI bus. 
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The adapter initialization module creates and prepares a channel request 

block, interrupt dispatch block, and an adapter control block in the manner 

described in this section. For each data structure it creates, VMS fills in the 
first three longwords with the standard VMS header information aa is, the 
structure type, size, and links). 


Channel Request Block 


For the newly created channel request block (CRB), VMS performs the 
following tasks: 


e Sets up the resource wait queue header (CRB$L_WQFL and CRB$L_ 
WQBL) 


e Sets the bit CRB$V_UNINIT in CRB$B_MASK to indicate to the 
System Generation Utility that, although the CRB exists, its controller 
initialization routine has not yet been called 


e Initializes four interrupt dispatchers (CRB$L_INTD, CRB$L_INTD2, and 
so On) so that they have the effect of pushing general registers RO through 
R5 onto the stack, and issuing a JSB instruction 


The adapter initialization module always creates the four vectors, in contrast 
to the methods by which UNIBUS/Q22 bus drivers control the number of 
vectors created (see Section 12.3.3). The destination of the JSB instruction at 
initialization is a standard null interrupt handler which merely dismisses the 
interrupt. Later, when the specific device driver is loaded for the device (see 
Section 14.8), the driver’s interrupt service routine address replaces this null 
interrupt handler in the dispatchers. As necessary, the driver specifies the 
addresses of its interrupt service routines as follows: 


DPT_STORE,CRB,CRB$L_INTD ,D,isr_for_ist_vector 

DPT_STORE , CRB, CRB$L_INTD2+VEC$L_ISR,D,isr_for_2nd_vector 

DPT_STORE , CRB, CRB$L_INTD+ (2*VEC$K_LENGTH) +VEC$L_ISR ,D,isr_for_3rd_vector 
DPT_STORE , CRB, CRB$L_INTD+ (3*VEC$K_LENGTH) +VEC$L_ISR ,D,isr_for_4th_vector 


Interrupt Dispatch Block 
VMS initializes the interrupt dispatch block (IDB) in the following manner: 


¢ Sets the number of device units controlled by this interrupt dispatch block 
(IDB$W_UNITS) to 1. The list of unit control block (UCB) addresses 
in this IDB, as a result, is one longword in size. The driver-loading 
procedure writes a UCB address into this longword whenever it creates a 
new UCB associated with the controller. Because there is only one slot in 
this array, drivers for non-DIGITAL-supplied multiunit controllers must 
use a different mechanism to locate the UCB of interest at the time of an 
interrupt. 


e¢ Copies the virtual address of the base of this device’s node space to 
IDB$L_CSR from the corresponding slot in the SBICONF array. 
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Adapter Control Block 


VMS creates a truncated adapter control block (ADP) for a non-DIGITAL- 
supplied VAXBI device (48 bytes as opposed to the traditional 600 bytes). The 
ADP it creates contains no fields reserved for the allocation and accounting of 
data paths or map registers. VMS prepares this generic ADP in the following 
manner: 


e Copies the virtual address of the base of this device’s node space to 
ADP$L_CSR from IDB$L_CSR. 


e Places the VAXBI node ID of this device in ADP$W_TR. 


e Stores the value AT$_GENBI (signifying the generic VAXBI ADP type) in 
ADP$W_ADPTYPE. 


e Calculates the address of the first of the four interrupt vectors for this 
node in the system control block (SCB), and places it in ADP$L_— 
AVECTOR. A driver can determine the addresses of the other three 
SCB vectors by adding 64, 128, or 192, respectively, to the address of this 
first SCB vector. 


e Saves the offset of this first SCB vector from the start of its SCB page in 
ADP$W_BI_VECTOR. (Refer to Section 14.3.2 for a description of the 
SCB.) | 


e Places in ADP$L_BI_IDR a longword mask with a single bit set, as 
appropriate to the VAX system, that specifies which VAXBI node should 
become the destination of interrupts from this node. In VAX 8200/ 
8250/8300/8350 systems, the VAXBI node of the primary processor 
becomes the destination for interrupts. In VAX 8530/8550/8700/8800, 
VAX 8830/8840, and VAX 6200-series systems, it is the VAXBI node of 
the NBIB, PBIB, or DWMBA/B on the particular VAXBI bus on which this 
device resides that becomes the destination for such interrupts. 


e Stores in ADP$L_MBASCB—and in each of the device’s four SCB 
vectors—the address of the interrupt dispatcher. The actual stored value 
is CRB$L_INTD+1, CRB$L_INTD2, and so on, the set low bit of the 
address indicating that the interrupt stack be used to service the interrupt. 
Certain powerfail recovery operations use the contents of ADP$L— 
MBASCEB to refresh the SCB vectors. 


e Saves in ADP$L—MBASPTE the contents of the first of the 16 SPTEs 
that map the device’s node space. Certain recovery operations use the 
contents of ADP$L_MBASPTE to restore correct SPTE values and remap 
node space following a power failure. 


e Places in ADP$L_BIMASTER the address of the ADP of the memory- 
interconnect-to-VAXBl-adapter (NBI, PBI, or DWMBA). Note that there is 
no memory-interconnect-to-VAXBI adapter for VAX 8200/ a 
8300/8350 configurations. 
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14.3.2 System Control Block 


The system control block (SCB) consists of one or more pages of vectors. 
For all VAX processing systems, the first half page contains vectors used in 
exception dispatching. VMS uses the remainder of the first page, as well as 
subsequent pages, in a system-specific way. 


For VAX 8200/8250/8300/8350 systems, VMS assigns the vectors from 10046 
to 1FC;¢ to VAXBI devices in the order of their node IDs. 


The VAX 8530/8550 /8700/8800/8830/8840 and VAX 6200-series system 
architectures relegate vectors 1001, to 1FC;¢ to NMI nexus vectors. 

Page 1 is reserved for the first “offsettable” device that exists in the system. 
(An “offsettable” device is an adapter such as the BI-to-UNIBUS adapter 
(DWBUA) that passes interrupts from devices on another bus to the 
VAXBI and, from there, to the memory interconnect (NMI or XMI) and 
the processor.) If there is more than one “offsettable” device, an additional 
SCB page is needed for each. 


Ultimately, the vectors for other devices attached to each of the six possible 
VAXBI buses of the system are contained in the six corresponding SCB pages 
from page 26 to page 31. In a 4-VAXBI system, for instance, vectors for 
devices connected to VAXBI 0 and VAXBI 1 on NBI/PBI/DWMBA 0 are 
assigned to pages 28 and 29 of the SCB, respectively; vectors for devices 
connected to VAXBI 0 and VAXBI 1 on NBI/PBI/DWMBA 1 are likewise 
assigned to pages 30 and 31. In a 6-VAXBI system, the vectors are assigned 
in a similar fashion, starting at page 26. 


Generally, a VAX processor obtains a device vector from the BIIC registers of 
the node that has requested the interrupt (see Figure 14-4). Information 
supplied in the device vector allows the processor to index to the 
corresponding interrupt-dispatching vector in the appropriate page of the 
SCB. For VAX 8200/8250/8300/8350 systems, such information includes the 
interrupt level of the device and its VAXBI node ID. A similar vector for VAX 
8530/8550/8700/8800, VAX 8830/8840, or VAX 6200-series devices further 
specifies the appropriate NBI/PBI/DWMBA vector offset and the number of 
the VAXBI bus. 


The specific SCB interrupt-dispatching vector, thus found, transfers control to 
the interrupt-dispatching code in the device’s CRB. Upon an interrupt from 
this device, the SCB vector directs flow into the interrupt dispatcher in the 
CRB, which saves the register contents and dispatches to the interrupt service 
routine established by the device driver. 


14.4 Initialization Performed by the VAXBI Device Driver 


All generic VAXBI device drivers must specify GENBI as the adapter type in 
the adapter argument to the DPTAB macro. 


The device driver’s initialization routines are expected to initialize the device- 
specific aspects of the VAXBI device. For non-DIGITAL-supplied devices, the 
initialization routines perform the sort of tasks that the adapter initialization 
module performs for the DIGITAL-supplied devices it discovers on a VAXBI 
bus. For single-unit devices, a separate unit initialization routine may not be 
necessary. 
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Figure 14-4 VAXBI Device Vectors 


For VAX 8200/8250/8300/8350 
131211109 8 76 543 2 1 


For VAX 8530/8550/8700/8800/8830/8850 and 
VAX 6200 Series Devices 


9876543 2 1 
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Register 





ZK-5545-86 





The VMS System Generation Utility (SYSGEN) calls the controller 
initialization routine at IPL 31, passing it the following values in the listed 
general registers: 


¢ R4 pointing to the system virtual address of the device’s node space 

e R5 pointing to the IDB 

e R6 pointing to the DDB 

e R8 pointing to the CRB 

After the controller initialization routine has completed, SYSGEN calls the 


driver's unit initialization routine at IPL 31, and passes it the following values 
in the listed general registers: 


e R3 pointing to the system virtual address of the device’s node space 


e RS pointing to the UCB 


Hardware initialization might include such activities as writing values to 
BIIC and device-specific registers, examining the results of the BIIC self test, 
mapping a node’s window space, building data structures to control the 
device, and linking these structures into chains of similar data structures. 


This section provides some ideas and guidelines for code that may be 
necessary in an initialization routine. There is no requirement that driver 
code perform all of the functions discussed here. The needs of various 
devices differ, and some devices make more demands on driver software than 
others. 


Code examples in the section assume that R4 initially contains the virtual 
_ address of the base of the device’s node space and R8 contains the virtual 
address of the device’s CRB. 
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14.4.1 Examining BIIC Self-Test Status 


According to the hardware specification for all devices attached to a VAXBI 
bus, a VAXBI node undergoes a self test on power failure recovery and at 
system boot time. The BIIC indicates the successful completion of the self test 
by setting BIIC$V_STS and by clearing BIIC$V_BROKE in BIIC$L_BICSR. 


A driver unit initialization routine should test these bits before performing 
any transaction on the VAXBI bus. If BIIC$V_STS is clear, then self test is still 
under way. If BIIC$V_BROKE is set, then the driver action is implementation- 
specific. In any event, a driver should not set UCB$V_ONLINE in UCB$L_— 
STS if the node is not usable. 


The maximum duration of the BIIC self test is ten seconds. If a VAXBI node 
implements the maximum self-test time, then the driver unit initialization 
routine may have to spin wait for the setting of BIIC$V_STS (for instance, 
by embedding the testing instructions in an invocation of the TIMEDWAIT 
macro). Driver unit initialization routines should perform this spin wait only 
when UCB$V_POWER in UCB$L_STS is set. Otherwise, the driver is being 
loaded by SYSGEN, and a long spin wait at high IPL will have adverse effects 
on the rest of the VMS system. 


Normally, only diagnostics initiate a self test by setting the SST bit in the 
BIIC. A VAXBI driver that sets this bit must take special precautions to avoid 
a machine check and to avoid undetected corruption of VAXBI memory. 
These precautions include the following steps: 


1 Use the $PRTCTINI macro to begin a machine check protection block, 
supplying the location of the end of the block in the label argument and 
the mask value # <MCHK$M_NEXM!MCHK$M_LOG> in the mask 
argument. (Note that you must include an invocation of the $MCHKDEF 
macro in the driver to use these symbols.) Code within the block executes 
at IPL 31. 


2 Disable arbitration on the VAXBI node being reset by setting BIIC$V_ 
ARBCNTRL in BIIC$L_BICSR. 


3 Set BIIC$V_SST and BIIC$V_STS simultaneously to initiate the self test. 
Do not set BIIC$V_SST in the same instruction that disables arbitration. 


4 Use the $PRTCTEND macro to end the machine check protection block. 
You must specify in the label argument the same value you specified in 
the label argument to the $PRTCTINI macro. 


5 Do not access the BIIC registers for at least one millisecond. You may not 
even check the state of the STS bit during this interval. 


6 Do not access any other address on the VAXBI node until the self test has 
completed. 
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14.4.2 Clearing BIIC Errors, Setting Interrupts, and Enabling Interrupts 
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14.4.2.1 


14.4.2.2 


There is a set of tasks that a VAXBI driver should perform during initialization 
that ensures that interrupts are properly enabled and delivered to an 
appropriate VAXBI target node. These tasks include the following: 


e Clearing any outstanding set bits in the Bus Error Register. 
e Setting the target node for interrupts in the Interrupt Destination Register. 
e Setting the device interrupt vector in the Error Interrupt Control Register. 


e Setting the device interrupt vector in the User Interface Interrupt Control 
Register. 


e Enabling hard and soft error interrupts as required by the device. 
' Typically hard errors are enabled and soft errors are disabled. 


e¢ Enabling interrupts upon certain types of transactions to user interface 
CSR space. 


It is important that the interrupt vectors and destination be set up before BIIC 
hard error and soft error interrupts are enabled. An error occurring while 
error interrupts are enabled but the vector is not initialized could lead to an 
invalid condition. 


Clearing the Bus Error Register 
The following example clears all set bits in the Bus Error Register (BIIC$L_ 
BER) to prevent spurious or pending error interrupts at initialization. 


MOVL BIIC$L_BER(R4) , - :Clear all set write-1-to-clear 
BIIC$L_BER (R4) ; bits in BIIC$L_BER 


Loading the Interrupt Destination Register 

The Interrupt Destination Register (BIIC$L_IDR) specifies which VAXBI node 
should become the destination of interrupts from this node. In VAX 
8200/8250/8300/8350 systems, the VAXBI node of the primary CPU 
becomes the destination for interrupts. In VAX 8530/8550/8700/8800, 

VAX 8830/8840, and VAX 6200-series systems, the VAXBI node of the NBIB, 
PBIB, or DWMBA/B on the particular VAXBI on which this device resides 
becomes the destination for such interrupts. 


The VMS system initialization procedure described in Section 14.3 creates a 
32-bit mask with the appropriate bit set and stores it in ADP$L_BI_IDR. If 
a driver must set the Interrupt Destination Register, it can simply move this 
value to the BIIC register: 


MOVL CRB$L_INTD+VEC$L_ADP (R8) , RO 
;Get ADP address 
MOVL ADP$L_BI_IDR(RO) , - ;Write to IDR 
BIIC$L_IDR(R4) 
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Setting Interrupt Vectors 

A VAXBI node uses the Error Interrupt Control Register (BIIC$L__EICR) 

to determine the SCB vector through which to interrupt when a BIIC at 

this node detects a bus error. The User Interface Interrupt Control Register 
(BIIC$L__UICR) similarly controls the operation of interrupts initiated by the 
device at this node. A driver can also use the Error Interrupt Control Register 
to support a device that generates secondary interrupt vectors. 


Because the VMS system initialization procedure described in Section 14.3 
saves the offset of the node’s first SCB vector from the start of its SCB page in 
ADP$W_BI_VECTOR, a driver can initialize both of these registers by using 
code similar to that in the following example: 


MOVL CRB$L_INTD+VEC$L_ADP (R8) ,RO ;Get ADP address 
MOVZWL ADP$W_BI_VECTOR(RO) ,R2 ;Get device vector 
MOVL BIIC$L_UICR(R4) ,BIIC$L_UICR(R4) ;Clear user vector 
MOVL R2,BIIC$L_UICR(R4) ;Set user vector 


BISL #1@<BIIC$V_LEVEL+BIIC$S_LEVEL-1>,R2 
;OR in interrupt level 
;BR7 in this case 
MOVL BIIC$L_EICR(R4) , BIIC$L_EICR(R4) ;Clear error vector 
MOVL R2,BIIC$L_EICR(R4) ;Set error vector 


Note that the driver clears both vectors before it actually sets them. Clearing 
BIIC$L_UICR and BIIC$L_EICR causes any pending interrupt to be cleared. 
Also note that the interrupt level must be set in BIIC$L_EICR, in this case 
BR7. If the level is not set, an interrupt will never be generated. 


Enabling Error Interrupts 

Finally, to enable interrupts that report errors detected by the node’s BIIC, 
the controller initialization routine can set the soft error interrupt-enable or 
hard error interrupt-enable bits in the VAXBI Control and Status Register. 
The BIIC sets bits in the Bus Error Register (BIIC$L_—BER) to reflect the type 
of bus error reported by the interrupt. 


BISL #<BIIC$M_SEIE!BIIC$M_HEIE>, - ;Soft error interrupt enable 
BIIC$L_BICSR(R4) ;Hard error interrupt enable 


Enabling BIIC Options 

Device registers are in the area of node space called user interface CSR 
space, and are located following the 256 bytes reserved for the BIIC-required 
registers. Use of user interface CSR space is implementation-dependent. 


For the processor to be alerted to various transactions directed at user 
interface CSR space, the controller initialization routine of devices that 
support such transactions should set appropriate bits in the BCI Control and 
Status Register (BIIC$L_BCICR). See Table 14-1 for definitions of these bits. 


The following example enables a node to alert the node specified as the 
interrupt destination (in BIIC$L—IDR) when a retry timeout, STOP command, 
or read or write transaction is directed at its user interface CSR space. 


BISL #<BIIC$M_STOPEN! - ;Stop enable 
BIIC$M_RTOEVEN! - ;Retry timeout enable 
BIIC$M_UCSREN>, - ;User CSR enable 


BIIC$L_BCICR(R4) 
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Each VAXBI, starting at address 204000004. in its I/O address space, provides 
16 address blocks of 256K bytes apiece, called window space. VAXBI nodes 
can use window space if it is necessary to map VAXBI transactions to memory 
space on a target bus, although only such nodes as the DWBUA adapter 
currently use this feature. 


Whereas the VMS initialization routine maps each VAXBI node’s node space 
to virtual addresses, it does not automatically map each node’s window 
space. If a device needs to use its window space, it is up to the driver’s unit 
initialization routine to map this space. 


First of all, the driver must determine the starting physical address of 

the node’s window space. Figure 14-3 illustrates how VAXBI addresses 
are constructed. Drivers can use the following VMS-supplied macros (in 
SYS$LIBRARY:LIB.MLB) to access pertinent VAXBI addresses and values: 


$IO8SSDEF (for VAX 8200/8250/8300/8350 systems) 
$IO8NNDEF (for VAX 8530/8550/8700/8800 systems) 
$IO8NNDEF and $IO8PSDEF (for VAX 8830/8840 systems) 
$IO9CCDEF (for VAX 6200-series systems) 


A driver calculates the starting address of a node’s window space by first 
determining the offset to the start of the VAXBI node’s window space from 
the beginning of its VAXBI I/O space. To do so, it performs the following 
tasks: 


1. Extracts the VAXBI node ID from bits <3:0> of ADP$W_TR. 


2 Multiplies the VAXBI node ID with the size of window space. The driver 
obtains this value from the following symbols: 


Symbol System 

-108SS$AL_NDSPER VAX 8200/8250/8300/8350 
IO8NN$AL _NDSPER VAX 8530/8550/8700/8800/8830/8840 
lO9CC$C_BIWSIZ VAX 6200 series 


3 Adds the address of the window space of VAXBI node 0 to this value. 
The driver obtains this value from the following symbols: 


Symbol System 

lO8SS$AL __NODESP VAX 8200/8250/8300/8350 . 
IO8NN$AL__NODESP VAX 8530/8550/8700/8800/8830/8840 
lO9CC$C_BIWINDOW VAX 6200 series 


The driver for a device on a VAX system configured with more than one 
VAXBI bus (for instance, the VAX 8530/8550/8700/8800/8830/8840 or VAX 
6200-series systems) must proceed to calculate the start of the I/O address 
space of the VAXBI bus to which the device is attached. It adds the result of 
the following steps to the value it has obtained above: 


1 Determine the offset to the I/O address space of the VAXBI bus to which 
the node is attached. 
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For VAX 6200-series systems, a driver first must obtain the XMI node 

ID of the NBI, PBI, or DWMBA to which the VAXBI is connected. It 
determines the address of the NBI’s, PBI’s or DWMBA’s ADP at offset 
ADP$L_BIMASTER of the node’s ADP. It then finds the XMI node of the 
NBI, PBI, or DWMBA at offset ADP$W_XBIA_TR of the ADP. 


For VAX 8530/8550/8700/8800/8830/8840 configurations, a driver 
obtains the VAXBI bus number from bits <7:4> from offset ADP$W_ 
TR of the node’s ADP. 


2 Multiply this value by 2000000,,¢, the amount of physical address space 
allocated for each VAXBI bus. 


3 Add to this value the base of I/O address space. The driver obtains this 
value from the following symbols: 


Symbol System 

lO8SS$AL_IOBASE VAX 8200/8250/8300/8350 
IOSNN$AL_IOBASE VAX 8530/8550/8700/8800/8830/8840 
IO9CC$AL_IOBASE VAX 6200 series 


After performing these calculations, the driver must associate each page 

of window space to be used with a system page-table entry (SPTE) that 
maps the page-frame number (PFN) of the physical page in window space 
to a system virtual address. VMS includes the routine LDR6ALLOC_PT, 
described in Appendix B, that allocates system page-table entries (SPTEs) for 
a specified number of pages. 


Because LDRSALLOC_PT executes at IPL$_SYNCH (holding the MMG 
spin lock in a VMS multiprocessing system), the controller initialization 
routine must fork from IPL$_POWER to fork IPL (using the CRB fork block) 
prior to calling it. See Section 11.1.5 for a discussion of forking in a driver 
initialization routine. 


Finally, once the SPTEs have been allocated, the driver moves the PFNs of 
the window space pages into the SPTEs, sets their valid bits, and initializes 
them in a device-specific manner. 





The method by which a device accomplishes direct-memory-access (DMA) 
transfers depends upon the characteristics of the device. As part of a VAXBI 
read or write transaction, such a device must place on the VAXBI bus a 
physical address, the target of which is a memory node or a node (such as an 
NBIB adapter) that transmits the request to memory across another bus. 


For the DMA device to successfully access the memory pages of a buffer 
involved in an I/O transfer, it must be given sufficient information as to 
the size and location of these buffer pages, the type of transaction that is 
requested, an offset into the first page of the buffer, and the length of the 
transaction. In addition, if the size of the transaction causes it to exceed the 
boundaries of a page, the device must have some means of accessing the 
remaining pages—even if they are, as is most likely, scattered throughout 
physical memory. 
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As a result, devices make use of several types of structures, the purpose of 
which is to help generate a succession of contiguous physical addresses on 
the VAXBI bus, that map to the various pages of the buffer involved in the 
transfer. Some possible strategies of this sort include the following: 


e A physically contiguous buffer in memory 
e System page tables in system memory 
e Process page tables locked in system memory 


¢ Map registers in the device’s VAXBI I/O address space 


A separate but related issue results from the fact that the original buffer, as 
specified in the user $QIO request, is in process space and is mapped by 
process page-table entries. Because the driver cannot rely on process context 
existing at the time the device is ready to service the I/O request, it must 
have some means of guaranteeing that it can access both the data involved in 
the transfer and the page-table entries that map the buffer. 


VMS supplies two separate techniques, applied by traditional VMS drivers 
and described in Section 6.3.1. © 


e Direct I/O, the technique used most commonly by DMA drivers, locks the 
user buffer in memory as well as the page-table entries that map it. Such 
a driver calls a VMS-supplied FDT routine that prepares the user buffer 
for direct I/O. 


e Buffered I/O is the strategy whereby the driver FDT routine allocates a 
buffer from nonpaged pool. It is this intermediate buffer that is involved 
in the DMA transfer. The FDT routine copies the data from the user 
buffer to the system buffer for a write request; I/O postprocessing 
routines deliver data from the system buffer to the user buffer for a 
read request. 


That DMA drivers may make use of either VMS direct I/O or buffered I/O 
is one way by which these drivers can supply specific information needed 
by the device to accomplish a DMA transfer. Those driver FDT routines that 
call a VMS direct-I/O FDT routine provide the following information in the 
device’s unit control block (UCB): 


UCB$L_SVAPTE Virtual address of the system page-table entry (SPTE) 
for the first page used in the transfer 

UCB$W.BOFF Byte offset in the first page of the transfer buffer 

UCB$W_BCNT Size in bytes of the transfer 


FDT routines for buffered I/O call EXESALLOCBUF, EXE$DEBIT_BYTCNT_ 
ALO, or EXE$DEBIT_BYTCNT_BYTLM_ALO to obtain a nonpaged pool 
buffer (debiting a job’s byte count quota in the last two routines) and initialize 
the same UCB fields with the following information: 


UCB$L_SVAPTE Virtual address of system buffer used in the !1/O 
transfer 

UCB$W_BOFF Number of bytes to be charged to the process for the 
transfer 

UCB$W_BCNT Size in bytes of the transfer 
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If a driver’s fork process must manipulate the data in any way at fork level 
(that is, outside of the driver's FDT routines), then it needs a virtual address 
it can use to access the data. Such a requirement could cause the driver 
writer to consider structuring the driver so that it uses buffered I/O. For 
short transfers, this need also could be accommodated by the driver’s loading 
an SPTE with the correct PFN and computing the associated system virtual 
address. The drivers for the disks that have ECC correction applied by the 
host do this when there is an ECC error detected. The controller can tell 
the driver that the error in the data in memory can be corrected by applying 
some pattern to a part of the data, but the fork process has to perform the 
correction, not the controller. 


MOVL IRP$L_SVAPTE(R3) ,R2 ;Get address of system buffer 

SUBW3  #12,8(R2) ,UCB$W_BCNT(R5) ;Calculate system buffer length 
BICW3 #C*<VA$M_BYTE>, (R2),UCB$W_BOFF ;Put offset in buffer 

EXTZV #VA$V_VPN,#VA$S_VPN(R2) ,R2 ;Get system virtual page number 
MOVL G°MMG$GL_SPTBASE, R1 ;Get address of system page table 
MOVAL £(R1) [R2] , UCB$L_SVAPTE(R5) ;Get system virtual address of page 


14.5.1 Example: DMB32 Asynchronous/Synchronous Multiplexer 


The DMB32 asynchronous/synchronous multiplexer can use any of four 
different modes of address translation for DMA accesses. Under each of these 
modes, the DMB32 requires that its driver supply an address by which it can 
either directly or indirectly obtain the pages of the buffer that is involved in 
the transfer. The four different translation modes require such addresses in 
one of the following forms: 


1 System virtual address of a buffer 

2 System virtual address of a page-table entry 
3 Physical address of a page table 

4 Address of a physically-contiguous buffer 


System Virtual Address of a Buffer and System Virtual Address of a 
Page-Table Entry 


The DMB32 can itself perform the first two types of address translation 
because it can read entries in the VMS system page table (see the VAX/VMS 
Internals and Data Structures manual for a description of page-table entries). 
The controller initialization routine of a DMB32 device driver supplies the 
physical address and length of the VMS system page table, plus the virtual 
address and length of the VMS global page table. It also sets a page-table- 
valid bit in a device maintenance register. 


As a result, a driver for a DMB32 device could use either direct I/O or 
buffered I/O, and accordingly load a device register with the system virtual 
address of the page-table entry that maps the buffer or the system virtual 
address of the buffer itself. After the driver has loaded other device registers 
with a buffer offset value and a transfer size—and set the “start” bit in a 
DMB32 line-control register—the DMB32 performs the transfer without any 
additional mapping or other driver intervention. 
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Physical Address of a Page Table 


In this mode, the DMB32 can be given the physical address of a page table 
that maps the I/O transfer. The DMB32 architecture mandates that each 
page-table entry be four bytes long and that the page table be aligned on a 
longword boundary. Also, each page is 512 bytes long. However, the page 
table can be anywhere in memory, possibly at a range of VAXBI I/O-space 
addresses belonging to the node to which the DMB32 adapter is attached. 
To perform a DMA transfer under this addressing mode, the DMB32 adapter 
requires the offset of the first byte of the buffer that is in the page described 
by the page-table entry. Each page-table entry contains bits <29:9> of the 
physical address of the page that is to be accessed. 


In this case, the driver must extract the PFNs of the pages involved in the 
transfer and insert them into the page table of the device. The following is 
an example of a routine that translates a system virtual address to a physical 
address. It returns the physical address at the top of the stack. 


VIRT_TO_PHYAD: 


PUSHL (SP) ;Create slot at top of stack 
; for return value 
PUSHR #°M<RO,R1,R2,R3> ;Save registers 
BICL3 #-512,R1,R0 ;RO = byte offset of address 
EXTZV #VA$V_VPN,- ;Extract VPN 
#VA$S_VPN,R1,R2 ; and put it in R2 
MOVL G*MMG$GL_SPTBASE, R3 ;R3 => system page table 
MOVL (R3) [R2] ,R3 ;R3 => PTE 
EXTZV #PTE$V_PFN,- ;Get page frame number of buffer 
#PTE$S_PFN ,R3,R3 ; page into R3 
ASHL #VA$V_VPN ,R3,R3 ;Shift into place for physical 
; address 
BISL3 RO,R3,20(SP) ;Put result into stack slot 
POPR #°M<RO,R1,R2,R3> ;Restore registers 
RSB ;Return to caller 


Physical Address of a Buffer 


If the device can neither read system page tables nor has its own scatter- 
gather map—and must perform a DMA transfer that spans physical pages—it 
must rely upon the actual contiguity of the physical pages involved in 

the transfer. Because there is no guarantee that this is the state of the user’s 
buffer, the driver must allocate an intermediate buffer consisting of contiguous 
physical pages. The driver never deallocates this buffer unless the driver is 
being unloaded by means of SYSGEN’s RELOAD command. (The driver 
unloading routine can call COM$DRVDEALMEM to do so.) The best time 

to allocate such a buffer is during the device's se ae when memory is 
most likely to be contiguous. 


The VMS routine EXESALOPHYCNTG, described in Appendix C, allocates 
such a buffer. The size of the buffer that should be allocated depends on the 
device’s characteristics and the size of the transfers requested on the device. 
A buffer of four pages is likely to be large enough for most disk transfers, for 
example; but if you have enough memory on your system, you might want 
to make your buffer the size of a disk track in order to reduce disk latency. 
In any event, large transfers to the device can be segmented into transfers the 
size of your intermediate buffer. 


The start-I/O routine of such a driver copies the data from the user’s buffer 
into the intermediate, physically contiguous buffer by means of the routine 
IOCSMOVFRUSER. 
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The driver then sets up the device for the DMA transfer: 


1 Determines the physical address of the buffer from the system virtual 
address returned by EXES/ALOPHYCNTG 


2 Moves the address to the device address register 
3 Activates the device 


4 If the transfer size exceeds the size of the buffer, returns to step 1 


When a user requests a transfer from such a device, the driver moves the data 
from the device to the intermediate, physically contiguous buffer by means 
of a DMA transfer, then calls IOCSMOVTOUSER to copy the data into the 
user’s buffer. 





Unit Initialization Routine 


A generic VAXBI device driver may include a unit initialization routine, in 
addition to its controller initialization routine, if it services a multiunit device. 


SYSGEN attempts to create a UCB and call the unit initialization routine for 
the number of units specified in the maxunits argument to the DPTAB macro. 


When called in the process of driver loading, the unit initialization routine 
of a generic VAXBI device driver must therefore determine if the unit it is 
currently servicing actually exists. Prior to returning control to SYSGEN, the 
routine must place in RO a success status (low bit set) if the unit exists or a 
failure status (low bit clear) if it does not. If SYSGEN receives failure status, 
it deallocates the UCB for the unit and proceeds to configure the next unit in 
a similar manner. 





Register Dumping Routine 


In the event of a device error or a VAXBI bus error, a driver’s register 
dumping routine should contain code that makes certain interesting registers 
available for error logging. Apart from any device registers that should be 
saved, the following BIIC registers may contain information important in 
determining the cause of the error: the Device Register (BIIC$6L_DTREG), the 
VAXBI Control and Status Register (BIIC$L_—BICSR), the Bus Error Register 
(BIIC$L_BER), the Error Interrupt Control Register (BIIC$L__EICR), and the 
Interrupt Destination Register (BIIC$L_IDR). 


The following is an example of part of a register dumping routine that saves 
the contents of these BIIC registers in an error buffer. 


MOVL BIIC$L_DTREG(R4) , (RO) + ;Device Type Register 

MOVL BIIC$L_BICSR(R4) , (RO) + ;BIIC CSR Register 

MOVL BIIC$L_BER(R4) , (RO) + ;Bus Error Register 

MOVL BIIC$L_EICR(R4) , (RO) + ;Error Interrupt Control Register 
MOVL BIIC$L_IDR(R4) , (RO) + ;Interrupt Destination Register 


14-19 


14.8 


Generic VAXBI Device Support 
14.8 Loading a VAXBI Device Driver 





Loading a VAXBI Device Driver 


The System Generation Utility (SYSGEN) loads the device driver into 
system virtual memory, creates additional data structures for the device 
unit, connects the device’s interrupt vectors, and calls the device driver’s 
controller initialization routine and unit initialization routine. 


Chapter 15 discusses the SYSGEN commands commonly used during driver 
loading. The following discussion pertains to those aspects of the loading 
process that specifically relate to the support of non-DIGITAL-supplied VAXBI 
devices. 


Because the autoconfigure facility cannot recognize non-DIGITAL-supplied 
VAXBI devices, the system startup procedure (or a later invocation of 
SYSGEN) must explicitly request that SYSGEN connect the device. SYSGEN 
responds to such explicit requests by utilizing the data structures created by 
the adapter initialization module for the unknown VAXBI device to load the 
associated device driver and invoke its initialization routines. 


For example, suppose that an unknown VAXBI device were located at 
node 3 on a given VAXBI bus, and that the software device driver for this 
device were known as “ZZDRIVER”. During adapter initialization, VMS 
would have encountered an unknown type of VAXBI device at node 3 and 
would have performed the following operations: 


e Mapped the node space for node 3 into system virtual memory 

¢ Constructed various data structures to govern the future operation of this 
device 

SYSGEN executes in response to the following commands: 


$ RUN SYS$SYSTEM: SYSGEN 
SYSGEN> CONNECT ZZA0: /ADAPTER=3 


SYSGEN performs the following activities: 


1 Searches the list of ADPs in the system to find the ADP for this VAXBI 
node (node 3) and, in turn, locates the corresponding CRB and IDB by 
following pointers in the ADP. 


2 Loads ZZDRIVER into system virtual memory. If the /DRIVER qualifier 
is specified, SYSGEN loads the specified driver instead. 


3 Creates a UCB for device ZZAO and places the address of the device’s 
CRB in that UCB. SYSGEN also initializes other UCB fields at this time. 


4 Sets the first entry in the IDB UCB array (IDB$L__UCBLST) to point to 
the new UCB. 


5 Creates a DDB for the ZZA device/controller combination. This allows 
user programs to assign I/O channels to device ZZAO later. This DDB, in 
turn, points to the location in memory where ZZDRIVER has been loaded 
and to the UCB for the ZZAO device. 


° Because the autoconfigure facility will never be called for a non-DIGITAL-supplied device, any unit delivery 
routine that a VAXBI device driver may include will never be called. 
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6 Calls the controller initialization routine in ZZDRIVER at IPL 31. 
7 Calls the unit initialization routine in ZZDRIVER at IPL 31. 


If you did not specify GENBI as the adapter type in the adapter argument 
to the DPTAB macro, the CONNECT command will fail with the 
following error message: 


#SYSGEN-E-INVVEC, invalid or unspecified interrupt vector 





14.9 — BIIC Register Definitions 


Note: 


Each VAXBI node is required to implement a minimum set of registers 
contained in specific locations within the node’s node space. VMS 
automatically maps each node’s node space at boot time and provides the 
macro $BIICDEF (in SYS$LIBRARY:LIB.MLB) to define offsets to the BITC 
registers and their significant bit fields. 


The contents of the BIIC registers are illustrated in Figure 14-5 and described 
in Table 14-1. See the VAXBI Options Handbook for a discussion of the BIIC 
and the rules for configuring its registers. 


Fields marked “Reserved to DIGITAL” are reserved for DIGITAL’s future 
use and should contain zeros. 
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Figure 14—5 Backplane Interconnect Interface Chip (BIIC) Registers 
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Table 14-1 Contents of the BIIC Registers 


Field Name 


BIIC$L_DTREG 


BIIC$L_BICSR 


'Read-only field. 


Contents 


Device Register. 


BIIC$L_DTREG consists of the following two words: 


BUCSW_DEVTYPE 


BlIC$W_REVCODE 


Device type. This field is written by device hardware 
and self-test microcode. It contains two bit fields: 


BICSV_MEMNODE (bits <14:8> ), when clear, 
indicates a memory node. 


BIIC$V_NONDEC (bit 15), when clear, indicates a 
DIGITAL-supplied device; it should be 1 otherwise. 


Revision code. 


VAXBI Control and Status Register. 
The following fields are defined within BIIC$L_BICSR. 


BIIC$V_NODE_ID' 


BIIC$V_ARBCNTL 


BIICS V_SEIE 


BIIC$V_HEIE 


BIICSV_UWP 


ae 


Node ID. This field is automatically loaded during the 
powerup sequence. Reserved to DIGITAL. 


Arbitration mode used by the node. Currently, all 
arbitration modes except dual round-robin arbitration are 
reserved to DIGITAL. Correspondingly, these two bits 
should be clear. When these two bits are set, arbitration 
is disabled, thus preventing a node from starting a 
VAXBI transaction. 


Soft error interrupt enable. When set, this bit allows 
the node to generate an interrupt when the soft error 
summary bit (BIIC$V_SES) in this register is set. 


Hard error interrupt enable. When set, this bit allows 
the node to generate an interrupt when the hard error 
summary bit (BIIC$V_HES) in this register is set. 


Unlock write pending. When set, this bit signals that 
the master port interface at this node has successfully 
completed an IRCI (Interlock Read with Cache Intent) 
transaction. The node clears this bit when it successfully 
completes a corresponding UWMCI (Unlock Write Mask 
with Cache Intent) instruction. 


Reserved to DIGITAL. Must be zero. 
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Table 14—1 (Cont.) Contents of the BIIC Registers 


Field Name Contents 
BIICSV_SST 


BIIC$V_STS 


BIIC$ V_BROKE? 


BIIC$SV_INIT2 


BIIC$V_SES' 


BIIC$V_HES' 


BIICSV_BIICTYPE' 


BIIC$V_BIICREVN' 
BIIC$L__BER Bus Error Register. 


Node reset. This bit is normally used by diagnostics to 
initiate the BIIC internal self test. Prior to initiating a BIIC 
self test, a node should disable arbitration by setting 
both bits in BIIC$V_ARBCNTL. When BIIC$V_SST is set, 
the self-test status bit (BIIC$V_STS) in this register must 
also be set. 


Reads to BIIC$V_SST return a zero. 


Self-test status. When set, this bit indicates that the 
BIIC has passed its self test. The controller initialization 
routine of a VAXBI device driver should inspect this 

bit and the BIIC$V_BROKE bit before proceeding with 
any VAXBI transactions. During the self-test sequence, 
BIIC$V_STS will automatically be reset by the BIIC to 
allow the proper recording of the new self-test results at 
the end of self test. 


Broke bit. When cleared by the device's self test, this 
bit indicates that the device has passed its self test. The 
controller initialization routine of a VAXBI device driver 
should inspect this bit and the BIIC$V_STS bit before 
proceeding with any VAXBI transactions. 


Initialization bit. 


Soft error summary. When set, this bit indicates that 
one or more of the soft error bits in the Bus Error 
Register (BIIC$L_BER) is set. 


Hard error summary. When set, indicates that one or 
more of the hard error bits in the Bus Error Register 
(BIICS$L__BER) is set. 


BIIC type. These bits <23:16> always contain 
00000001. 


BIIC revision number. 


The following bits are defined within BIIC$L_BER. Bits <30:16> are hard error 


bits and bits <2:0> 
BIIC$V_NPE? 


BIIC$V_CRD? 
BIIC$V_IPE? 
BIICSV_UPEN' 
<14:4> ' 
BIIC$V_ICE? 
BIIC$V_NEX? 


1Read-only field. 


are soft error bits. 


Null bus parity error. 

Corrected read data. 

ID parity error. 

User parity enabled. 

Reserved to DIGITAL. Must be zero. 
Illegal confirmation error. 


Nonexistent address. 


2Write-one-to-clear bit. Write-type transactions cannot set this bit. 
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Table 14-1 (Cont.) Contents of the BIIC Registers 


Field Name 


BIIC$L_EICR 


'Read-only field. 


Contents 
BIIC$V_BTO? 
BIIC$V_STO? 
BIIC$V_RTO? 
BIIC$V_RDS? 
BIIC$V_SPE? 
BIIC$V_CPE* 
BIIC$V_IVE? 
BIC$V_TDF? 
BIIC$V_ISE* 
BIIC$V_MPE? 
BIIC$V_CTE? 
BIIC$V_MTCE? 
BIIC$V_NMR? 
<31> 


Bus timeout. 

Stall timeout. 

Retry timeout. 

Read data substitute. 

Slave parity error. 

Command parity error. 

IDENT vector error. 

Transmitter during fault. 

Interlock sequence error. 

Master parity error. 

Control transmit error. 

Master transmit check error. 

NO ACK to multiresponder command received. 
Reserved to DIGITAL. Must be zero. 


Error Interrupt Control Register. This register supplies information the node uses to 
request and monitor the status of both BllC-detected and forced-error interrupts: 
that is, those interrupts signaled by either the setting of a bit in the Bus Error 
Register (BIIC$L_BER) or the setting of the force bit (BINC$V_EIFORCE) in this 
register, respectively. The node can initiate BIlC-detected error-interrupt requests 
only if the appropriate error-interrupt enables (BIICS$V_SEIE and/or BIIC$V_HEIE) are 
set in the VAXBI Control and Status Register (BIIC$L_BICSR). 


The following fields are defined within BIICSL_EICR. 


<1:0> ! 
BIiC$V_EIVECTOR 
<15:14> ' 
BNC$V_LEVEL 


BIIC$V_EIFORCE 


BIIC$V_EISENT? 
<22> 
BIICSV_EINTC2 


Reserved to DIGITAL. Must be zero. 
12-bit vector used in error interrupt sequences. 
Reserved to DIGITAL. Must be zero. 


These four bits (<19:16> ) correspond to the four 
interrupt levels (INT <7:4> ) of the VAXBI bus. A set 
bit causes the corresponding level to be used when INTR 
commands under control of this register are transmitted. © 


Force bit. When set, this bit posts an error interrupt 
request in the same way as a bit set in the Bus Error 
Register (BIIC$L_BER), except that the request is not 
qualified by the bits BIIC$V_HEIE and BIIC$V_SEIE in 
BIIC$L_BICSR. 


INTR sent. 
Reserved to DIGITAL. Must be zero. 


INTR complete. When set, this bit indicates that the 
vector for an error interrupt has been successfully 
transmitted or an INTR command sent under the control 
of this register has been successfully aborted. 


2Write-one-to-clear bit. Write-type transactions cannot set this bit. 
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Table 14—1 (Cont.) 
Field Name 


BIICSL_IDR 


BIICSL_IPIMR 


BIICSL __IPIDR 


BIIC$SL _IPISR? 


BIIC$L_SAR 


BIIC$L_EAR 


BIIC$L__BCICR 


'Read-only field. 


Contents of the BIIC Registers 
Contents 


BIIC$V_EIINT AB? INTR abort. When set, this bit indicates that an INTR 
command under the control of this register has been 
aborted (that is, a NO ACK or illegal confirmation code 
has been received). This bit is a status bit set by the 
BIIC and can be reset only by the user interface. 


<31:25> ! Reserved to DIGITAL. Must be zero. 


Interrupt Destination Register. The low-order word of this register indicates which 
nodes are to be selected by INTR commands. 


Interprocessor Interrupt Mask Register. The high-order word of this register 
indicates which nodes are permitted to send interprocessor interrupts to this node. 


Force-bit IPINTR/STOP Destination Register. The low-order word of this register 
indicates which nodes are to be targeted by force-bit IPINTR or STOP commands 
sent by this node. 


IPINTR Source Register. The BIIC stores in the high-order word of this register the 
decoded ID of a node that sends an IPINTR command to this node. 

Starting Address Register. The Starting Address Register and Ending Address 
Register define storage blocks in either memory or |/O space. They must not be 
configured to include node space or multicast space. 

The low-order 18 bits of this register must be zero. This means that memories 
are multiples of 256K bytes. Software should set up the Starting Address Register 
before the Ending Address Register. 

Ending Address Register. 

The low-order 18 bits of this register must be zero. This means that memories 
are multiples of 256K bytes. Software should set up the Starting Address Register 
before the Ending Address Register. See the description of the Starting Address 
Register (BIICSL__SAR) for further details.. 

BCI Control Register. 


The following fields are defined within BIIC$L __BCICR. 


<2:0>:' Reserved to DIGITAL. Must be zero. 
BIIC$V_RTOEVEN RTO EV enable. 

BIIC$ V_PNXTEN Pipeline NXT enable. 

BIIC$ V_IPINTREN IPINTR enable. 

BIICS V_INTREN - INTR enable. 

BlIC$V_BICSREN BIIC CSR Space enable. 
BIIC$V_UCSREN User Interface CSR Space enable. 
BIIC$ V_WINVALEN WRITE Invalidate enable. 
BUC$V_INVALEN INVAL enable. 

BIIC$ V_IDENT IDENT enable. 

BIIC$V_RESEN RESERVED enable. 


2Write-one-to-clear bit. Write-type transactions cannot set this bit. 
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Table 14—1 (Cont.) Contents of the BIIC Registers 


Field Name Contents 


BIIC$V_STOPEN 
BIIC$V_BDCSTEN 


STOP enable. 
BDCST enable. 


BIIC$V_MSEN Multicast Space enable. 
BIICSV_IPINTRF IPINTR/STOP force. 
BIIC$V_BURSTEN Burst enable. 
<31:18> ' Reserved to DIGITAL. Must be zero. 
BIIC$6L_WSR Write Status Register. 
The following fields are defined within BIICSL_WSR. 
<270>' Reserved to DIGITAL. Must be zero. 
BIIC$ V_GPRO? Indicates that a VAXBI transaction has written to General 
Purpose Register O (BIIC$L__GPRO). 
BIIC$V_GPR 12 Indicates that a VAXBI transaction has written to General 
Purpose Register 1 (BIIC$L__GPR1). 
BIIC$V_GPR2? Indicates that a VAXBI transaction has written to General 
Purpose Register 2 (BIIC$L_GPR2). 
BIIC$V_GPR32 Indicates that a VAXBI transaction has written to General 
Purpose Register 3 (BIIC$L__GPR3). 
BIIC$SL_IPISTPF Force-Bit IPINTR/STOP Command Register. 


The following fields are defined within BIIC$L_IPISTPF. 


<10:0> ! Reserved to DIGITAL. Must be zero. 

BIIC$V_MIDEN Master ID Enable. 

BIIC$ V_CMD These four bits indicate the command code for either an 
IPINTR or STOP transaction that is initiated by setting 
the IPINTR/STOP force bit (BICSV_INTRF in BIIC$L_— 
BCICR). 

<31:16> ' Reserved to DIGITAL. Must be zero. 

BIIC$L_UICR User Interface Interrupt Control Register. This register controls the operation of 


interrupts initiated by the device. 
The following fields are defined within BIIC$L__UICR. 


<1:0> ' 
BIIC$V_UIVECTOR 


1Read-only field. 


Reserved to DIGITAL. Must be zero. 


These 12 bits contain the vector used during user 
interface interrupt sequences (unless the external vector 
bit (BIICSV_EXVECTOR in BIIC$L_UICR) is set). The 
vector is transmitted when this node wins an IDENT 
arbitration that matches the conditions given in BHC$L_ 
UICR. 


2Write-one-to-clear bit. Writé-type transactions cannot set this bit. 
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Table 14—1 (Cont.) Contents of the BIIC Registers 


Field Name Contents 
<14> Reserved to DIGITAL. Must be zero. 
BIIC$V_EXVECTOR When set, the BIIC solicits the interrupt vector from the 
node rather than transmitting the vector contained in 
BIICSL_UICR. 
BIIC$V_UIFORCE These four bits correspond to the four interrupt levels - 
(INT <7:4> ). When a bit is set, the BIIC generates an 
interrupt at the indicated level. 
BIIC$V_UISENT2 These four bits correspond to the four interrupt levels 
(INT <7:4> ). A set bit indicates that an INTR command 
for the corresponding level has been successfully 
transmitted. 
BIIC$V_UIINTC? These four bits correspond to the four interrupt levels 
(INT <7:4> ). A set bit indicates that the vector 
for an interrupt at the corresponding level has been 
successfully transmitted or that an INTR command sent 
under the control of this register has been successfully 
aborted. 
BIIC$V_UIINT AB? These four bits correspond to the four interrupt levels 
(INT <7:4> ). A set bit indicates that an INTR command 
at the corresponding level, sent under the control of this 
register, has been aborted (that is, a NO ACK or illegal 
confirmation code has been received). 
BIICSL__GPRO General Purpose Register O. 
BIICSL_—GPR1 General Purpose Register 1. 
BIIC$L__GPR2 General Purpose Register 2. 
BIICSL__GPR3 General Purpose Register 3. 


2Write-one-to-clear bit. Write-type transactions cannot set this bit. 
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You can load a non-DIGITAL-supplied device driver any time after the system 
is bootstrapped. If the driver contains an error and the error does not crash 
or corrupt the operating system, you can correct the error and reload a new 
version of the driver. 





15.1 Preparing a Driver for Loading into the Operating System 


To prepare a device driver for loading, perform the following steps: 


1 


Write the device driver in one or more source files. If the driver comprises 
several source files, you must insert a .PSECT directive before any 
generated code in all files except the file that contains the DPTAB and 
DDTAB macro invocations. The following .PSECT must be used: 


.PSECT $$$115_DRIVER 


If a single source file contains the driver, you must not specify any 
.PSECT directives. The declaration of the DPTAB and DDTAB macros 
correctly establishes driver program sections ($$$105_PROLOGUE and 
$$$115_DRIVER, respectively). 


Assemble the source file(s) with the system’s macro library 
(SYS$LIBRARY:LIB.MLB). For example: 


¢ MACRO MYDRIVER.MAR+SYS$LIBRARY : LIB .MLB/LIBRARY 


Link the object file with the VMS global symbol table, which is located in 
SYS$SYSTEM and called SYS.STB. If the driver consists of several source 
files, you must specify the file that contains the driver prologue table 

as the first file in the list. The linker-options file must contain a BASE 
statement specifying a zero base for the executable image. The following 
is an example of the creation of the options file and the LINK command 
used to link a driver: 


$ CREATE MYDRIVER.OPT 


BASE=0 

¢ LINK /NOTRACE MYDRIVERi(,MYDRIVER2,...],- 
_$ MYDRIVER.OPT/OPTIONS, - 

_$ SYS$SYSTEM: SYS .STB/SELECTIVE_SEARCH 


The resulting image must consist of a single image section. The linker 
will report that the image has no transfer address. 


Once you have linked or relinked a driver, you should copy its image to the 
SYS$LOADABLE_IMAGES or SYS$SYSTEM directory. The SYSGEN LOAD 
and CONNECT commands first search for a driver in the SYS$LOADABLE_ 
IMAGES directory. If they do not find the driver, they then search the 
SYS$SYSTEM directory. 
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15.2 Loading a Driver 


15.2.1 LOAD Command 
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Note: 


Once the driver has been linked correctly, it is ready to be loaded. To load 
the driver into system virtual memory, run the System Generation Utility 
(SYSGEN) from the system manager’s account or from an account having 
CMKRNL privilege, using the following command: 


$ RUN SYS$SYSTEM: SYSGEN 
SYSGEN responds with a prompt and waits for further input: 
SYSGEN> 


The VMS System Generation Utility Manual describes the full set of SYSGEN 
commands. The sections that follow describe those commands SYSGEN uses 
to load drivers: 


SYSGEN Command Privilege Required 
LOAD CMKRNL 
CONNECT CMKRNL 
RELOAD CMKRNL 
SHOW/ADAPTER CMEXEC 
SHOW /CONFIGURATION CMEXEC 
SHOW /DEVICE CMEXEC 


SYSGEN takes special steps to ensure that drivers that do not adhere to 
multiprocessing synchronization standards do not coexist in a system with 
drivers that are properly synchronized. The procedure that SYSGEN follows 
to accomplish this is discussed in Section 15.3. In addition, SYSGEN provides 
an automatic configuration service for UNIBUS/Q22 bus devices, as described 
in Section 15.4. 


To load a device driver, issue the LOAD command. 


If the controller has only a single unit attached to it, you can issue 
the CONNECT command to perform the driver-loading tasks normally 
performed by the LOAD command, as well as its task of creating the 
device’s I/O database (see Section 15.2.2). 


Format 
LOAD filespec 


Parameter 


filespec 

Name of a file containing an executable driver image. The driver-loading 
procedure compares the name field (DPT$T_NAME) in the driver prologue 
table of the driver being loaded with the names of the drivers in the current 
system configuration. If the procedure discovers that a driver with the same 
name already exists in the configuration, it will not load the new driver. If 
it does not find a configured driver with the same name, it loads the new 
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driver into contiguous locations in nonpaged pool, and links the DPT into the 
system’s linked list of DPTs (headed by IOC$GL_DPTLIST). 


The LOAD command uses SYS$SLOADABLE_IMAGES as the default 
device/directory name, and EXE as the default file type. If it cannot find 
the driver in the SYS$SLOADABLE_IMAGES directory, it searches for it in 
SYS$SYSTEM. 


Example 
SYSGEN> LOAD CRDRIVER 


This command loads the driver found in SYS$LOADABLE_— 
IMAGES:CRDRIVER.EXE (the card-reader driver). 


15.2.2 CONNECT Command 


CAUTION: 


The CONNECT command creates data structures in the I/O database for a 
specified device. The device-connecting procedure performs the following 
general functions: 


e If the CONNECT command specifies a new device unit on an existing 
controller, it creates a unit control block for the new unit and calls the 
driver’s unit initialization routine. 


e If the CONNECT command specifies a device unit on a new controller, it 
creates a device data block, channel request block, interrupt dispatch 
block, and unit control block and then calls both the controller 
initialization and unit initialization routine in the driver. (Note that, 
because system initialization creates the CRB and IDB for a generic VAXBI 
device, the CONNECT command for such a device omits the creation and 
initialization of these structures.) 


The CONNECT command can also load into system memory a driver 
that has not been previously loaded. (See the following discussion of the 
/DRIVERNAME qualifier and the description of the LOAD command in 
Section 15.2.1 for information on driver loading.) 


The database-loading procedure does little error checking. If you specify a 
vector that has already been defined, the procedure rejects the CONNECT 
command. However, if the CONNECT command specifies an incorrect 
CSR address, the I/O database is apt to become corrupted and will likely 
cause a system failure. 


Format 
CONNECT device 
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Parameter 


device 


Name of the device to be connected. Specify the device name in the format 
ddcu where 


dd = device code (up to 9 alphabetic characters) 
c= controller designation (alphabetic) 
u= unit number 


For example, LPAO specifies the line printer (LP) on controller A at unit 
number 0. When specifying the device name, do not follow it with a 
colon (:). 


The device code and controller specification must be a unique and accurate 
device name and controller combination. If data structures for the specified 
device/controller already exist, the device-connecting procedure does not 
create any data structures or perform any initialization operations. If the 
device/controller name does not accurately name a device, the procedure 
creates spurious data structures. 


The device-connecting procedure examines the I/O database for data 
structures that support the specified device. The procedure creates the 
following data structures if they do not exist: 


¢ DDB for the specified device/controller combination (ddcu). 


e CRB and IDB for the specified controller. The device connecting 
procedure creates these data structures whenever it creates a DDB for 
a UNIBUS, MASSBUS, or Q22 bus device. 


¢ UCB for the device unit. The device-connecting procedure creates a UCB 
whenever it creates a DDB, or when a UCB for the specified device does 
not exist. If a UCB already exists, the procedure ceases its modifications 
to the I/O database and continues its other tasks. 


After it creates these data structures, the procedure initializes them as follows: 


e Performs the initialization operations specified by the DPT_STORE 
macros in the initialization and reinitialization portions of the DPT. 


e Relocates all addresses in the DDT and FDT to absolute system virtual 
addresses. . 


e Raises IPL to IPL$_POWER on the local processor so that initialization is 
not interrupted. 


e If it created a new CRB (or is connecting a generic VAXBI device), 


calls the controller initialization routine, if one is specified by CRB$L_ 
INTD+VEC$L _INITIAL. 


e Calls the unit initialization routine if one is specified by DDT$L_— 
UNITINIT. If the DDT$L_UNITINIT does not specify a unit initialization 
routine, the device-connecting procedure calls the unit initialization 
routine (if any) specified by CRB$L_INTD+VEC$L_UNITINIT. 
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Required Qualifiers 


/[NOJADAPTER=nexus 


Nexus value of the UNIBUS adapter, MASSBUS adapter, or other controller 
to which the device unit is attached. The nexus can be a number or a generic 
name as listed by the /ADAPTER qualifier to the SYSGEN command SHOW. 
(See Section 15.2.4 for a discussion of the SHOW/ADAPTER command.) For 
generic VAXBI devices, this value is the VAXBI node number. Table 15-1 lists 
typical nexus assignments for UNIBUS and MASSBUS adapters. 


Table 15—1 Conventional Nexus Assignments 
VAX-11/780 
VAX-11/785 VAX 8200 VAX 8530 
VAX 8600 VAX 8250 VAX 8550 
VAX-11/725 VAX 8650 VAX 8300 VAX 8700 
Adapter VAX-—11/730 VAX-11/750 VAX 8670 VAX 8350 VAX 8800' 
UNIBUS 
6) 3 8 3 0) 0 
1 - 9 4 - 0 
2 — - 5 - 0 
3 — - 6 - 0 
MASSBUS 
) - 4 8 - - 
1 - 5 9 - - 
2 - 6 10 _ = 
3 - 11 = = 


'The VAX 8530/8550/8700/8800 systems can provide up to four VAXBI buses. A DWBUA can be situated only at 
node O on a VAXBI and, thus, can have a nexus value of 0, 16, 32, or 48. 


All numeric values are interpreted as decimal unless they are preceded by 
a radix descriptor (%O or %X). Issue the CONNECT command with the 
/NOADAPTER qualifier to connect drivers associated with software devices. 
The mailbox driver is an example of this type of driver. 


/CSR=csr-addr 


UNIBUS or Q22 bus address of the device’s control and status register (CSR). 
All numeric values are interpreted as decimal unless they are preceded by a 
radix descriptor (%O or %X). Table 15-2 provides additional information on 
vector and CSR assignments for UNIBUS and Q22 bus devices. 


/CSR_OFFSET=value 

Offset from the CSR address of a multiple-device controller board to the CSR 
address of the device. The /CSR_OFFSET qualifier is only required for a 
multi-device board, such as the DMF32. All numeric values are interpreted 
as decimal unless they are preceded by a radix descriptor (%O or %X). 
Table 15-2 provides additional information on vector and CSR assignments 
for UNIBUS and Q22 bus devices. 
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/VECTOR=vector-addr 
Q22 bus or UNIBUS address of the interrupt vector for the device. All 
numeric values are interpreted as decimal unless they are preceded by a radix 


descriptor (%O or %X). Table 15-2 provides additional information on vector 
and CSR assignments for UNIBUS and Q22 bus devices. 


/VECTOR_OFFSET=value 

Offset from the interrupt vector of a multiple-device board to the interrupt 
vector of the device being connected. The /VECTOR—OFFSET qualifier is 
only required for a multi-device board, such as the DMF32. All numeric 
values are interpreted as decimal unless they are preceded by a radix 
descriptor (%O or %X). Table 15-2 provides additional information on 
vector and CSR assignments for UNIBUS and Q22 bus devices. 


Optional Qualifiers 


/NUMVEC=vector-cnt 

Number of interrupt vectors for the device. If this qualifier is omitted, the 
default number of vectors is 1. The number specified by the /VECTOR 
qualifier is the address of the lowest vector. Vectors must be contiguous. 


/DRIVERNAME=driver 

Name of the driver for the device to be connected. If the driver for the 
specified device has not yet been loaded, the CONNECT command will 

load its driver. First, it will attempt to load the driver whose name is 
specified in this qualifier, defaulting to a file type of EXE in device/directory 
SYS$LOADABLE_IMAGES. (If it cannot find the driver in SYS$SLOADABLE_ 
IMAGES, the CONNECT command checks SYS$SYSTEM.) 


If the /DRIVERNAME qualifier is omitted, CONNECT follows one of two 
procedures to supply a default name. If the device to be connected is the 
first unit on the controller, CONNECT concatenates the first two characters 
of the device code with “DRIVER,” (for example, LPDRIVER). Otherwise, 
CONNECT obtains the driver name from the field DDB$T_DRVNAME. 


Consult the SYSGEN device table in Table 15-2 for the driver names of the 
devices supported by VMS. 


/ADPUNIT=unit-number 

Unit number of a device on the MASSBUS adapter. The unit number for a 
disk drive is the number of the plug on the drive. For magnetic tape drives, 
the unit number corresponds to the tape controller’s number. 


/MAXUNITS=max-unit-cnt 

Maximum number of units attached to the controller. This number 
determines the size of the UCB list appended to the IDB. If specified, this 
value overrides the maximum number of units designated in the DPT. The 
maximum number of units is stored in the field IDB$W_UNITS. 


Example 
SYSGEN> CONNECT LPAO /ADAPTER=UBO/CSR=%0777514/VECTOR=%,0200 


This command loads the driver LPDRIVER, if it is not already loaded, and 
creates the data structures (DDB, CRB, IDB, and UCB) needed to describe 
LPAO. It also causes the driver’s controller and unit initialization routines to 
be executed. 
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15.2.3 RELOAD Command 


CAUTION: 


The RELOAD command loads a driver and removes a previously loaded 
version of that driver. 


The RELOAD command provides all of the functions of LOAD, except that it 
loads the driver regardless of whether it is already loaded. If any of the units 
associated with the driver is busy, the driver cannot be reloaded; SYSGEN 
issues an error message. 


Use the RELOAD command only when all devices supported by the 
driver are inactive. The checks for activity made by the RELOAD 
command might not detect all device activity, and changing a driver 
while an I/O request is being processed will cause a system failure. 


Format 


RELOAD filespec 


Parameter 


filespec 

Name of a file containing an executable driver image. The driver-reloading 
procedure compares the name DPT$T_NAME of the driver being loaded with 
the names of the drivers in the current system configuration. If no such driver 
is configured, the driver-reloading procedure loads the driver as described in 
the discussion of the LOAD command in Section 15.2.1. 


If the SYSGEN reloading procedure finds a driver with the specified name in 
the configuration, it first determines that the current driver can be replaced in 
the following steps: 


¢ Confirms that the DPT$V_NOUNLOAD flag of the current driver is not 
set. 


e Ensures that no devices that use the current driver are busy, as indicated 
by the UCB$V_BSY bit set in UCB$L_STS. 


e If these checks succeed, calls the current driver’s driver unloading routine, 
if one has been specified in the unload argument of the DPTAB macro. 


The driver unloading routine executes in process context at IPL$_ 
POWER. It cannot lower IPL or obtain spin locks. 


Registers at the time of the call contain the following values: 


Register Value 


R6 Address of DDB 
R10 Address of DPT 


A driver unloading routine can take steps to ensure that no thread of code 
or structure exists in the system that may reference the space occupied 
by the version of the driver about to be unloaded, a timer-queue element 
(TQE), for instance. 


A driver unloading routine can use COM$DRVDEALMEM to return 
system buffers allocated by the driver to nonpaged pool. The driver 
unloading routine returns status in RO to the driver-reloading procedure. 
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Upon receiving success status, the driver-reloading procedure replaces the 
current driver with the new driver in the following manner: 


1 Loads the new driver into contiguous locations in nonpaged pool. 


2 Searches the I/O database for references to the driver. If any DDB 
refers to the driver being reloaded, the driver-reloading procedure 
must reinitialize data structure fields according to the reinitialization 
instructions in the new DPT. (see Section 6.1). 


Fields that must be reinitialized when a driver is reloaded include those 
that contain relative addresses within the driver: 


e Addresses of the interrupt service routines 
e Addresses of the unit and controller initialization routines 
e Address of the driver dispatch table 


3 Calls the driver’s controller initialization routine. (It does not call the unit 
initialization routine.) 


4 Removes the newly replaced driver from the system’s linked list of DPTs 
(headed by IOC$GL_DPTLIST) and deallocates the nonpaged system 
space the old driver occupied. 


5 Links the address of the new DPT to the system’s DPT list. 


15.2.4 SHOW/ADAPTER Command 
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The SHOW/ADAPTER command displays nexus numbers and generic names 
of UNIBUS and MASSBUS adapters, VAXBI adapters, memory controllers, 
and interconnection devices such as the DR32 and CI. Use of the SHOW 
/ADAPTER command requires CMEXEC privilege. 


Format 
SHOW /ADAPTER 


Example 
SYSGEN> SHOW/ADAPTER 
CPU Type: VAX 8530 
Nexus Generic Name or Description 


32 CIO 

34 BI - NBIB Adapter 

38 BI Combo Board 

39 BI - AIE Adapter with NI port only 
48 UBO 

50 BI - NBIB Adapter 

52 BI - Disk Adapter (KDB50) 
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15.2.5 SHOW/CONFIGURATION Command 


The SHOW/CONFIGURATION command displays the device name, number 
of units, nexus number and type, and shows the CSR and vector addresses of 
devices connected to or autoconfigured in the system. 


Format 
SHOW /CONFIGURATION 


Optional Qualifiers 


/ADAPTER=nexus 


Nexus value of the UNIBUS adapter, MASSBUS adapter, or other 
interconnect to be displayed. The nexus value can be expressed as an integer 
or as one of the generic names listed by the SHOW/ADAPTER command. 


/COMMAND_ FILE 


Option by which you instruct SYSGEN to format all device data produced by 
the SHOW /CONFIGURATION command into CONNECT /ADAPTER=nexus 
commands and write them to a specified output file. By executing the 
commands in this file, you can remove a device from floating address 

space without completely reconnecting the CSR and vector addresses of 

the remaining devices. See the VMS System Generation Utility Manual for 
more details. 


/OUTPUT=filespec 
Name of a file into which SHOW/CONFIGURATION is to write device 
configuration information. 


Example 
SYSGEN> SHOW/CONFIGURATION/ADAPTER=UB1 


System CSR and Vectors on 24-JUL-1988 14:58:26.08 


Name: LPA Units: 1 Nexus:4 (UBA) CSR: 777514 Vectori: 200 Vector2: 000 
Name: DYA Units: 2 Nexus:4 (CUBA) CSR: 777170 Vectori: 264 Vector2: 000 
Name: XMA Units: 1 Nexus:4 (UBA) CSR: 760070 Vector1: 300 Vector2: 304 
Name: XMB Units: 1 Nexus:4 (UBA) CSR: 760100 Vector1: 310 Vector2: 314 
Name: XMC Units: 1 Nexus:4 (UBA) CSR: 760110 Vector1: 320 Vector2: 324 
Name: TTA Units: 8 Nexus:4 (UBA) CSR: 760130 Vector1: 330 Vector2: 334 
Name: TTB Units: 8 Nexus:4 (UBA) CSR: 760140 Vector1: 340 Vector2: 344 
Name: TTC Units: 8 Nexus:4 (UBA) CSR: 760150 Vector1: 350 Vector2: 354 
Name: TTD Units: 8 Nexus:4 (UBA) CSR: 760160 Vector1: 360 Vector2: 364 
Name: TTE Units: 8 Nexus:4 (UBA) CSR: 760170 Vector1: 370 Vector2: 374 


15.2.6 SHOW/DEVICE Command 
The SHOW/DEVICE command displays the following information: 
¢ Name of the driver 
e Starting virtual address of the driver (that is, the address of its DPT) 
e Ending virtual address of the driver 


e Generic device/controller name associated with the driver 
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e Addresses of the DDB, CRB, and IDB for the generic device /controller 


supported by the driver 


e Unit number and UCB address of each device unit associated with the 


driver 
The SHOW/DEVICE command requires CMEXEC privilege. 


Format 
SHOW /DEVICE [=driver-name] 


Parameter 


driver-name 

Name of the driver for which the information is to be displayed. If a driver 
name is not specified, the command displays information about all drivers 
and devices known to the system. 


Example 
SYSGEN> SHOW/DEVICE=TMDRIVER 
__DRIVER___START____END___DEV___DDB CRB IDB UNIT___UCB 


TMDRIVER 8009DFO00 8009F020 
MTA S8OOBA660 800BA6CO 800BA360 
0 8009F020 
1 8009F0CO 





15.3. Loading Uniprocessing and Multiprocessing Drivers 
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In a VMS multiprocessing environment, the presence of a device driver that 
does not adhere to multiprocessing synchronization conventions can be fatal 
to proper system functions. VMS takes steps to either prohibit the enabling 
of multiprocessing in a VAX system that has such a driver present or prevent 
the loading of such a driver if multiprocessing has already been enabled. 


To accomplish this, the VMS driver-loading routine assumes that any driver 
that can run in a VMS multiprocessing environment uses the spin lock 
synchronization macros and loads the appropriate I/O database fields. (See 
Section G.3 for information on how to produce a driver that can execute in a 
VMS multiprocessing environment.) Use of the spin lock synchronization 
macros causes VMS to set the SMP-modified bit in the DPT (DPT$V_ 
SMPMOD in DPT$L_FLAGS). 


If multiprocessing has not been enabled on the system, the driver-loading 
routine checks the SMP-modified bit in the DPT and takes either of the 
following actions: 


e If the SMP-modified bit is set, the driver-loading routine loads the driver 
and calls its controller and unit initialization routines, as discussed in 
Section 15.2. 


e If the SMP-modified bit is not set, the driver-loading mechanism sets 
the unmodified-driver bit (SGMP$V_UNMOD_DRIVER) in SMP$GL— 
FLAGS, thus prohibiting the subsequent enabling of multiprocessing 
on the system. It then loads the driver and calls its controller and unit 
initialization routines. If such a driver has been successfully loaded into a 
VMS system, you cannot subsequently enable multiprocessing. 
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If multiprocessing is currently enabled on the system, the driver-loading 
mechanism checks the SMP-modified bit in the DPT and takes either of the 
following actions: 


e If the SMP-modified bit is set, the driver-loading mechanism loads the 
driver and calls its controller and unit initialization routines. 


e =If the SMP-modified bit is not set, the driver-loading mechanism does 
not load the driver, returning the error status SS$_NONSMPDRV to its 
caller. 





15.4 The SYSGEN Autoconfiguration Facility 


Traditionally, SYSGEN is invoked near the end of system initialization 
processing during the execution of the system startup command procedure. 
This procedure generally issues a SYSGEN AUTOCONFIGURE ALL 
command, the result of which is that SYSGEN scans various device tables 

to determine devices VMS expects to be connected to each UNIBUS, Q22 
bus, MASSBUS, and VAXBI bus configured in the system. Ultimately, as the 
autoconfigure facility discovers the data structures associated with the devices 
recognized by VMS, it loads the associated device drivers and invokes their 
initialization routines. 


To configure devices attached to the UNIBUS or Q22 bus, SYSGEN goes 
through the steps described in subsequent sections of this chapter. Because 
the autoconfigure facility cannot recognize non-DIGITAL-supplied VAXBI 
devices, the system startup procedure (or a later invocation of SYSGEN) must 
explicitly request that SYSGEN connect the device. SYSGEN responds to 
such explicit requests by utilizing the data structures created by the VMS 
adapter initialization module for the unknown VAXBI device to load the 
associated device driver and invoke its initialization routines. 


SYSGEN automatically configures a UNIBUS or Q22 bus as follows: 


e It initializes the base of floating space to 300g and 760010, for vectors 
and CSRs, respectively. 


e It tests fixed and floating CSR address space for all known DIGITAL 
devices. 


e When a device is found at a CSR, SYSGEN reserves floating CSR and 
vector space for that device, if necessary. 


e It searches for the name of the driver associated with the device by 
checking the SYSGEN device table (shown in Table 15-2) and the 
directory SYS$LOADABLE_IMAGES (or SYS$SYSTEM). If the driver 
has already been loaded or exists as an image file in SYSSLOADABLE_ 
IMAGES (or SYS$SYSTEM), SYSGEN creates and initializes the I/O 
database for that device and loads the driver's image if necessary. If the 
device at the CSR is supported by VMS and SYSGEN cannot locate its 
associated driver’s image, it generates an error message. If the device is 
unsupported and has no corresponding driver’s image, SYSGEN ignores 
the condition. 
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15.4.1 SYSGEN Device Table 
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DIGITAL-supplied devices are attached to the UNIBUS or Q22 bus according 
to the following basic rules: 


e A device of type A is always at a fixed and predefined CSR address; the 
device always interrupts at a fixed and predefined vector address; only 
one example of device A can be configured in each system. 


e A device of type B is identical to type A except that 1 through n examples 
can be configured in a single system. Examples 2 through n are also 
located at fixed and predefined CSRs and vector addresses. 


e Devices of type C (1 through n of them) are always at fixed and 
predefined CSR addresses; however, the interrupt vector addresses vary 
according to what other devices are present on the system. 


e Devices of type D (1 through n of them) are at CSR addresses and vector 
addresses that vary according to what other devices are present on the 
system. 


CSR and vector addresses that vary are called floating addresses. The devices 
must be located in floating CSR and vector space according to the order in 
which the devices appear in the SYSGEN device table. This table, shown 

in Table 15-2, lists all the type A and type B devices supported by VMS. It 
also lists the type C and type D devices that are recognized by SYSGEN’s 
autoconfiguration procedure. 


The base of floating vector space is 300g. The base of floating CSR space is 
760010g. 


Table 15-2 lists the characteristics of all devices recognized by SYSGEN. This 
table indicates the following information for each device type: 


e Device name 

¢ Device controller name 

¢ Interrupt vector 

¢ Number of interrupt vectors per controller 
¢ Vector alignment factor 


e Address of the first device register for each controller recognized by 
SYSGEN (the first register is usually, but not always, the CSR) 


e¢ Number of registers per controller 
e ~=Device driver name 


¢ Indication of whether the driver is or is not supported 
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Devices not listed in the SYSGEN device table include the following: 


Non-DIGITAL-supplied devices with fixed CSR and vector addresses. 
These devices have no effect on autoconfiguration. Customer-built 
devices should be assigned CSR and vector addresses beyond the floating 
address space reserved for DIGITAL-supplied devices. 


Those DIGITAL-supplied floating-vector devices that the 
AUTOCONFIGURE command does not recognize. Use the CONNECT 
command to attach these devices to the system. 


Table 15-2 SYSGEN Device Table 


Device Controller 


Name 


CR 
DM 
LP 


DL 
Ms 
DY 
pa 
PU 
PT 
XE 
xa 
OM 


DD 


Name 


CR11 
RK611 
LP11 


RL11 
TS11 
RX211 
RB730 
UDA 
TU81 
UNA 
QNA 
DC11 


TU58 


Vector 


230 
210 


200 
170 
174 
270 
274 


160 
224 
264 
250 
154 
260 
120 
120 
Float 


Float 


Number 
of 
Vectors 
1 

1 


es ee ee 


Vector 


Alignment CSR/Rank 


777160 
777440 


777514 
764004 
764014 
764024 
764034 


774400 
772520 
777170 
775606 
772150 
774500 
774510 
774440 


774000 
774010 
774020 
774030 


32 units 
maximum 
776500 
776510 
776520 
776530 


16 units 
maximum 


Register 
Alignment 


Driver 
Name 
CRDRIVER 
DMDRIVER 
LPDRIVER 


DLDRIVER 
TSDRIVER 
DYDRIVER 
DODRIVER 
PUDRIVER 
PUDRIVER 
XEDRIVER 
XQDRIVER 
OMDRIVER 


DDRIVER 


Support 


Yes 
Yes 
Yes 


Yes 
Yes 
Yes 
Yes 
Yes 
Yes 
Yes 
Yes 
No 


Yes 
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Table 15-2 (Cont.) SYSGEN Device Table 


Device Controller 


Name 
OB 


YM 


OA 


PR 


PP 
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Name 
DN11 


DM11B 


DR11C 


PR611 


PP611 


Vector 


Float 


Float 


Float 


Float 


Float 


Number 
of 
Vectors 


1 


Vector 


Alignment CSR/Rank 


4 


775200 
775210 
775220 
775230 


16 units 
maximum 


770500 
770510 
770520 
770530 


16 units 
maximum 


767600 
767570 
767560 
767550 


16 units 
maximum 


772600 
772604 
772610 
772614 


8 units 
maximum 
772700 
772704 
772710 
772714 


8 units 
maximum 


Register 
Alignment 


Driver 
Name 


OBDRIVER 


YMDRIVER 


OADRIVER 


PRDRIVER 


PPDRIVER 


Support 
No 


No 


No 


Table 15—2 (Cont.) 


Device Controller 


Name 
OC 


OD 


YL 


YS: 
YH 
OE 


LS 

OR 
OF 
XU 
XV 


OG 
XM 
TTA 
XK 
OH 
Ol 
OJ 
OK 
DL 


Name 


DT 11 


DX11 


DL11C 


DJ11 
DH11 
GT40 


LPS11 
DQ11 
KW11W 
DU11 
DV11 


LK11 
DMC 11 
DZ11 
KMC 11 
LPP 11 
VMV21 
VMV31 
DWR70 
RL1 1 
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Vector 


Float 


Float 


Float 


Float 
Float 
Float 


Float 
Float 
Float 
Float 
Float 


Float 
Float 
Float 
Float 
Float 
Float 
Float 
Float 
Float 


Number 
of 
Vectors 


2 


B NM ND 


WO MO hw NY OD 


Pp YM NHM HY NY KM NH NH NY 


Vector 


Alignment CSR/Rank 


8 


0c © © 


co © © © © 


PF OO OW WO WH OHO OO 


777420 
777422 
777424 
777426 


8 units 
maximum 
776200 
776240 
775610 
775620 
775630 
775640 


31 units 
maximum 
Float 


Float 


~ 772000 


772010 
770400 
Float 
772400 
Float 


775000 
775040 
775100 
775140 


Float 
Float 
Float 
Float 
Float 
Float 
Float 
Float 
Float 
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Register 
Alignment 


a i A 


Driver 
Name 


OCDRIVER 


ODDRIVER 


YLDRIVER 


YJDRIVER 
YHDRIVER 
OEDRIVER 


LSDRIVER 

ORDRIVER 
OFDRIVER 
XUDRIVER 
XVDRIVER 


OGDRIVER 
XMDRIVER 
DZDRIVER 
XKDRIVER 
OHDRIVER 
OIDRIVER 
OJDRIVER 
OKDRIVER 
DLDRIVER 


Support 
No 


No 


No 


No 
No 
No 


No 
No 
No 


No 


No 
Yes 
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Table 15-—2 (Cont.) 


Device Controller 


Name 


MS 


LA 
LA 
OL 
DY 
XA 
XB 
XB 
XB 
XD 
ON 


XD 
XE 
XQ 
PU 
XS 
XP 


VB 
PT 

0a 
UK 


TX 
DT 
VC 
vc 
OT 
LD 
ZO 
ZO 
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Name 
TS11 


LPA11 
LPA11 
KW11C 
RX211 
DR11W 
DR11B 
DR11B 
DR11B 
DMP 11 
DPV 11 
ISB11 
DMV 11 
UNA 
QNA 
UDA 
KMS11 
PCL11 


VS100 
TU81 

KMV 11 
KCT32 


IEQ11 
DHV 11 
TC11 
VCBO1 
VCBO1 
LNV11 
LNV21 
QTA 
QTA 


SYSGEN Device Table 


Vector 


Float 


Float 
Float 
Float 
Float 
Float 
124 

Float 
Float 
Float 
Float 
Float 
Float 
Float 
Float 
Float 
Float 
Float 


Float 
Float 
Float 
Float 


Float 
Float 
214 

Float 
Float 
Float 
Float 
Float 
Float 


Number 
of 
Vectors 


1 


= —= NO RN BN 


wo Wp |= A NNN N - 


NM Ne = = 


= = ww ea LO PO — NO PO 


Vector 


Alignment CSR/Rank 


4 


age kate RS ri A AN ee SE, ee ee ee Se 


oo f ff 


BA P Pa a 


772524 
772530 
772534 


770460 
Float 
Float 
Float 
Float 
772410 
772430 
Float 
Float 
Float 
Float 
Float 
Float 
774460 
Float 
Float 


764200 
764240 
764300 
764340 


Float 
Float 
Float 


764400 
764440 
764500 
764540 


764100 
Float 
777340 
777200 
Float 
776200 
Float 
772570 
Float 


Register 
Alignment 


16 


16 


16 


64 


16 


Driver 
Name 


TSDRIVER 


LADRIVER 
LADRIVER 
OLDRIVER 
DYDRIVER 
XADRIVER 
XBDRIVER 
XBDRIVER 
XBDRIVER 
XDDRIVER 
ONDRIVER 
ISDRIVER 
XDDRIVER 
XEDRIVER 
XQDRIVER 
PUDRIVER 
XSDRIVER 
XPDRIVER 


VBDRIVER 
PUDRIVER 
OQDRIVER 
UKDRIVER 


IXDRIVER 

YFDRIVER 
DTDRIVER 
VCDRIVER 
VCDRIVER 
OTDRIVER 
LDDRIVER 
ZODRIVER 
ZODRIVER 


Support 


Yes 


Yes 
Yes 
No 


Yes 
No 
No 
No 
Yes 
No 
No 
No 
No 
Yes 
Yes 
No 
No 


No 
Yes 
No 
No 


No 
Yes 
No 
Yes 
Yes 
No 
No 
No 
No 
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Table 15—2 (Cont.) SYSGEN Device Table 


Number 

Device Controller of Vector Register Driver 
Name Name Vector Vectors Alignment CSR/Rank Alignment Name Support 
SJ DSV11 Float 1 4 Float 8 SJDRIVER No 
OU ADV11C Float 2 8 Float 8 OUDRIVER No 
OV AAV11C Float O 8 770440 — OVDRIVER No 
OV AAV11C Float O 8 Float 8 OVDRIVER No 
AX AXV11C 140 2 776400 — AXDRIVER No 
AX AXV11C Float 2 8 Float 8 AXDRIVER No 
KZ KWV11C Float 2 8 770420 — KZDRIVER No 
KZ KWV11C Float 2 8 Float 4 KZDRIVER No 
OF KWV11W Float 2 8 772400 — OFDRIVER No 
AZ ADV11D Float 2 8 776410 — AZDRIVER No 
AZ ADV11D Float 2 8 Float 4 AZDRIVER No 
AY AAV11D Float 2 8 776420 — AYDRIVER No 
AY AAV11D_ Float 2 8 Float 4 AYDRIVER No 
VA VCBO2 Float 3 16 777400 — VADRIVER Yes 

777402 

777404 

777406 

8 units 

maximum 
DN DRV11J Float 16 4 764160 —— DNDRIVER No 

764140 

764120 
HX DRO3B Float 2 8 Float 16 HXDRIVER No 
va VSV24 Float 1 4 Float 8 VODRIVER' No 
VV VSV21 Float 1 4 Float 8 VVDRIVER No 
BO IBOO1 Float 1 4 Float 8 BODRIVER No 
UT MIRA Float 2 8 Float 8 UTDRIVER No 
IX 1EQ11 Float 2 8 Float 16 IXDRIVER No 
AW ADQ32 Float 2 8 Float 32 AWDRIVER No 
VX DTCO4 Float 2 8 Float 2 VXDRIVER No 


15.4.2 Device Driver Control of Autoconfiguration 


The SYSGEN autoconfiguration facility provides two features that drivers 

can use to control the automatic configuration of the devices they operate. 
These features are invoked through the defunits and deliver arguments to 
the DPTAB macro. 
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Note: 


The defunits argument to the DPTAB macro specifies a default number of 
units to be configured on each controller. The DPTAB macro copies this value 
to the DPT$W_DEFUNITS field in the DPT. The SYSGEN autoconfiguration 
facility reads this field and creates UCBs numbered zero through the default 
unit number minus one. The default value of defunits is 1. 


The deliver argument to the DPTAB macro specifies the address of a driver- 
specific unit delivery routine. An offset to this routine is stored in the 
DPT$W_DELIVER field in the DPT. When the deliver argument is present, 
the SYSGEN autoconfiguration facility calls the unit delivery routine once for 
each unit, the number of which is specified in the defunits argument. 


Because the autoconfigure facility will never be called for a non- 
DIGITAL-supplied device, any unit delivery routine that a VAXBI device 
driver may include will never be called. 


The unit delivery routine prevents the creation of UCBs for devices that do 
not respond to a test for their presence. 


If the unit delivery routine returns a true status in RO, the unit is configured. 
If the status in RO is false, the autoconfiguration facility does not configure 
the device. If the deliver argument is not used, the unit delivery feature is 
disabled. 


SYSGEN calls the unit delivery routine with a JSB instruction in the following 
context: 


e Interrupt priority level is at IPL$_POWER. 
e RO through R2 are available for use. 


¢ R3 contains the address of the IDB, if one exists. If none exists, the value 
contained in R3 is zero. 


e R4 contains the address of the CSR for the controller. 


e R5 contains the number of the unit that the routine must decide whether 
or not to configure. 


e R6 contains the base address of UNIBUS adapter I/O space. 
e¢ 7 contains the address of the configuration control block (ACF). 
¢ R8 contains the address of the ADP. 


The configuration control block is described in Figure A—2 and Table A-1. 


A driver may or may not specify a unit delivery routine. For instance, the 
DZ11’s device driver specifies 8 as the default unit number, but provides no 
routine to configure eight terminal units automatically for each DZ11’s CSR. 
The RK611 device driver specifies 8 as the default number of units and also 
specifies the address of a unit delivery routine that is called once for each of 
the eight possible devices on the controller. 
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15.4.3 Floating-Vector Address Calculation 


To calculate the floating-vector address of a device, SYSGEN rounds the 
current floating-vector base (CFVB) up to the next valid vector address 
boundary for the next device in the table. 


If a device is present, SYSGEN reserves floating-vector space for the device 
by computing a new CFVB: 


CFVB + (4 * number-of-vectors) — CFVB 


15.4.4 Floating-CSR Address Calculation 


To calculate the floating CSR address of a device, SYSGEN rounds the current 
floating CSR base (CFCB) up to the next valid floating CSR address. Floating 
CSR addresses must fall on an 8-byte boundary. 


SYSGEN tests the CSR address (CFCB) for the next device in the device table 
by executing a TSTW instruction on the address and noting whether there is 
a response at that address. 


If the device is present, SYSGEN reserves floating CSR address space for the 
device by computing a new CFCB: 


CFCB + bytes-in-register-set + CFCB 
When all devices of a particular type have been located and their floating CSR 


space reserved, SYSGEN reserves an extra block of CSR space to indicate a 
change to a new device type: 


CFCB + 8 — CFCB 


If the device is not present, SYSGEN reserves an extra block of CSR space to 
indicate a change to a new device type by adding eight to the rounded CFCB: 


CFCB + 8 — CFCB 


15.4.5 Rules for Configuration 


The formulas described in Sections 15.4.3 and 15.4.4 reduce to the following 
maxims: 


¢ Devices with fixed CSR addresses and fixed vector addresses must be 
attached according to the SYSGEN device table settings. 


¢ Devices with floating CSR or vector addresses must be attached in the 
order in which they are listed in the SYSGEN device table. 


e An 8-byte gap must be reserved between each different type of device 
that is located in floating CSR address space. 


e An 8-byte gap must be reserved in floating CSR address space for each 
device type that has no controller in its configuration. 


e An extra 8-byte gap must be reserved between the KW11C and the RX11 
in floating CSR address space. 
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When assigning floating vector addresses and registers to devices not supplied 
by DIGITAL, be sure to leave a generous gap between these addresses and 
those of devices in the table because future VMS maintenance updates might 
add new devices to the SYSGEN device table.! 


" UNIBUS addresses 764100g through 767776g are available for non-DIGITAL-supplied devices. 
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1 6 Debugging a Device Driver 


DELTA and XDELTA are debugging tools that can be used to monitor the 
execution of user programs and the VMS operating system. When you link 
DELTA with a user image that runs in a nonprivileged process, DELTA is 

a user-mode debugging tool. When run in a privileged process, however, 
DELTA acts as a multimode debugger; it allows you to debug in user mode or 
to change to kernel mode for debugging. However, DELTA does not support 
debugging at elevated IPLs. 


XDELTA is syntactically identical to DELTA but also allows you to debug code 
that executes at an elevated IPL. XDELTA is used for stand-alone debugging 
of driver code and the executive. 


This chapter primarily describes the use of XDELTA as a tool for debugging 
an executing driver image. In the command syntaxes and dialogues contained 
in this chapter, red ink indicates the commands typed by the user and black 
ink indicates the system prompts and responses. 


The chapter includes discussions of two additional topics: 
e Detection and analysis of driver errors in a VMS multiprocessing system 


¢ Detection of corruption in nonpaged pool and the ways in which the 
corrupting code can be discovered 


These topics supplement information presented in the VMS System Dump 
Analyzer Utility Manual. 





16.1 Bootstrapping the System with XDELTA 


Under VMS, drivers are part of the operating system. You normally bootstrap 
the system with two boot flags set to allow you to debug with XDELTA. One 
flag causes the bootstrapping procedure to include XDELTA in the system. 
The other boot flag indicates a stop at the breakpoint at the beginning of 
VMS initialization. (The BREAKPOINTS system parameter, by default, 
enables a breakpoint at the end of system initialization. See Section 16.2 for 
additional information.) Table 16-1 describes the possible values of these 
flags. Following a boot that includes XDELTA, executing a BPT instruction 
causes control to transfer to a fault handler located in XDELTA. 
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Table 16—1 Boot Flags That Control the Loading of XDELTA 


Flag 

Value (f) Meaning 

) Normal nonstop bootstrap (default) 

1 Stop in SYSBOOT (equivalent to @DxyGEN on the VAX-—11/780) 

2 Include XDELTA with the system but do not take the initial 
breakpoint 

6 Include XDELTA with the system and take the initial breakpoint 

7 Include XDELTA with the system, stop in SYSBOOT and take the 


initial breakpoint at system initialization (equivalent to @DxyXDT 
on the VAX—11/780) 


The procedures for bootstrapping the system with XDELTA differ depending 
upon the system on which the operating system is running. Some VAX 
systems that use a console block storage device supply a special boot 
command file that automatically includes XDELTA in the system and causes 
the processor to stop in SYSBOOT and take the initial breakpoint at system 
initialization. When booting other systems, you must specify the appropriate 
flag value in the BOOT command. Table 16-2 lists some recommended 
methods for booting with XDELTA. See your system’s installation and 
operations guides for additional information. 


Table 16—2 Recommended Methods for Bootstrapping with XDELTA 


Boot Commands 


Explanation 


MicroVAX 3600-Series, MicroVAX I, MicroVAX |, and VAX—11/750' Systems 


B[/f]| devname 


B is the console BOOT command. The flags (f) parameter is a 32-bit hexadecimal 
integer loaded into R5 as input to VMB.EXE, the primary bootstrap program. See 
Table 16-1 for a list of its possible values. 


Using the format ddcu, specify the name of the device that contains the volume 
to be bootstrapped. You must supply both controller (c) and unit (u) identifiers; 
there are no defaults. If you omit devname, the f parameter is ignored. 


The following example bootstraps a MicroVAX II system from DUAO.” 
>>>B/7 DUAO 


SYSBOOT> 
SYSBOOT>CONTINUE 





'The console TU58 of the VAX—11/750 system contains command files (DMAXDT.CMD and DBAXDT.CMD) analogous 
to those supplied for the VAX—11/780. See your system’s installation and operations guides for additional information. 


2At the SYSBOOT prompt enter other required SYSBOOT commands and conclude the boot operation with a CONTINUE 
command. If you do not set or load system parameters with a USE command, the system uses parameters stored in 
the system image. To prevent the system from automatically rebooting after a bugcheck, clear the BUGREBOOT system 


parameter. 
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Recommended Methods for Bootstrapping with XDELTA 


Explanation 


VAX 6200-Series Systems 


B[/R5:f] 
[/XMI:xmi_node_id] 
[/Bl: vaxbi_node_id] 
devname 


B is the console BOOT command. The flags (f) parameter is a 32-bit hexadecimal 
integer loaded into R5 as input to VMB.EXE, the primary bootstrap program. See 
Table 16—1 for a list of its possible values. 


Specify devname in the format ddduuu, identify the location of the memory- 
interconnect-to-VAXBI adapter (XBIA) in /XMI qualifier and the VAXBI node id 
of the device in the /BI qualifier. (You can substitute a symbolic name for these 
qualifiers as discussed in your processor-specific operations guide.) 


The console places the specified unit number (uu) in R3 and executes the procedure 
dddBOO.COM. If you do not specify devname, the console executes DEFBOO.COM. 
To use the /R5 qualifier to the BOOT command, you must have previously removed 
or commented out the DEPOSIT R5 command in the procedure to be executed. 


The following example bootstraps a VAX 6240 system from the boot disk at 
node 3 of the VAXBI bus at node 15 of the XMI.? 


>>>B/R5:7/XMI:E/BI:3 DUO 
SYSBOOT> 
SYSBOOT> CONTINUE 


VAX 8200/8250/8300/8350 and VAX 8530/8550/8700/8800/8830/8840"Systems 


B[/R5:f| devname 


B is the console BOOT command. The flags (f) parameter is a 32-bit hexadecimal 
integer loaded into R5 as input to VMB.EXE, the primary bootstrap program. See 
Table 16-1 for a list of its possible values. 


For the VAX 8530/8550/8700/8800/8830/8840, specify devname in the format 
ddduuu. The console places the specified unit number (uuu) in R3 and executes 
the procedure dddBOO.COM. If you do not specify devname, the console executes 
DEFBOO.COM. 


To use the /R5 qualifier to the BOOT command for VAX 8530/8550/8700/8800 
systems, you must have previously removed or commented out the DEPOSIT R5 
command in the procedure to be executed. For VAX 8830/8840 systems, data 
specified in the /R5 qualifier to the BOOT command overrides data specified in the 
DEPOSIT R5 command in the boot command procedure. 


For the VAX 8200/8250/8300/8350, specify devname in the format ddxu, where 
x represents the number of the VAXBI node to which the boot device unit is 
attached. If you do not specify devname, the console boots from the default boot 
device. 


The following example bootstraps a VAX 8200 system from the boot disk at 
VAXBI node 4.? 


>>>B/R5:7 DU40 
SYSBOOT> 
SYSBOOT> CONTINUE 


2At the SYSBOOT prompt enter other required SYSBOOT commands and conclude the boot operation with a CONTINUE 
command. If you do not set or load system parameters with a USE command, the system uses parameters stored in 
the system image. To prevent the system from automatically rebooting after a bugcheck, clear the BUGREBOOT system 


parameter. 


3Note that the console prompt for the VAX 8830 and 8840 systems is PS-CIO-O> and not >>>. 


16-3 


Debugging a Device Driver 
16.1 Bootstrapping the System with XDELTA 


Table 16—2 (Cont.) Recommended Methods for Bootstrapping with XDELTA 


Boot Commands 


Explanation 


VAX-—11/780 and VAX-11/785 Systems 


@DMAXDT 
@DBAXDT 


Use either DMAXDT.CMD or DBAXDT.CMD, depending upon the boot device. The 
following example boots from DMAQO, first depositing the value O in R3.? 


>>>DEPOSIT R3 0 
>>>@DMAXDT 
SYSBOOT> 
SYSBOOT>CONTINUE 


VAX-11/730 and VAX-11/725 Systems 


@DQAXDT 
@DQOXDT 


Use either DOAXDT.CMD or DOOXDT.CMD, depending upon the boot device. The 
following example boots from DQA1, first depositing the value 1 in R3. When the 
boot device is DOAO, you can omit this step and execute DOOXDT.COM.? 


>>>D/G/L 3 1 
>>>@DQAXDT 
SYSBOOT> 
SYSBOOT>CONTINUE 


VAX 8600/8650/8670 Systems 


@DUOXDT 


Use DUOXDT.COM, if available on the console media, according to the method 
described for the VAX—11/780. Otherwise, perform a normal bootstrap using the 
available dduGEN.COM or dduBOO.COM according to the following method: 


Use the /NOSTART qualifier in the BOOT command to cause the processor to 
pause and await console commands after it boots. After a variety of progress 
messages are displayed, the console prompt reappears. First, determine a value 
for the flag that controls XDELTA loading (see Table 16—1). Then, examine the 
current value of R5; if it is nonzero (for instance, it is the system root number), 
perform an inclusive-OR operation upon it and your selected XDELTA flag value.” 


>>>BOOT/NOSTART 
SYSBOOT>EXAMINE R5 
SYSBOOT>DEPOSIT R5 7 
SYSBOOT> 
SYSBOOT>CONTINUE 


2At the SYSBOOT prompt enter other required SYSBOOT commands and conclude the boot operation with a CONTINUE 
command. If you do not set or load system parameters with a USE command, the system uses parameters stored in 
the system image. To prevent the system from automatically rebooting after a bugcheck, clear the BUGREBOOT system 


parameter. 
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16.2 Proceeding from the Initial Breakpoints 


Before stopping at any breakpoints that may be defined in driver code, 

the VAX processor can stop at either or both of two breakpoints in system 
initialization. 

The breakpoint at the end of system initialization is enabled by the default 
setting of the BREAKPOINTS system parameter. The breakpoint at the 
beginning is enabled by the appropriate value of the boot flag as described in 
Table 16-1. 


After being bootstrapped, the system displays its welcoming message and 
halts in XDELTA, as follows: 


1 BRK AT nnnnnnnn 
address/NOP 


XDELTA is waiting for input. (XDELTA never issues explicit prompts.) 
Usually, you proceed from this point with the following command: 


;P RET 


All of the XDELTA commands are described in Section 16. 10 and in the VMS 
Delta/XDelta Utility Manual. 


If the operating system halts with a fatal bugcheck, the system prints 
the bugcheck information on the console terminal. Then, because the 
BUGREBOOT system parameter is clear, XDELTA prompts. Bugcheck 
information consists of the following: 


¢ Type of bugcheck 

e¢ Register values 

e Dump of one or more stacks 

PC and stack content indicate how an experimental driver crashed the 


system. You can then examine the system state further by issuing XDELTA 
commands. 





16.3 Loading the Driver 


Once the system is running, you can log in to the system as the system 
manager and load the experimental driver. 


To load the driver, run SYSGEN and issue the appropriate LOAD and 
CONNECT commands. Example 16-1 provides a sample dialogue. 


The first SHOW command in Example 16-1 causes SYSGEN to display the 
location of the device driver in system memory. You then define the device 
to the operating system. The second SHOW command causes SYSGEN to 
display the driver’s location and the addresses of the device’s DDB, CRB, IDB, 
and UCB. 
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Example 16—1 Loading a Driver 


$ RUN SYS$SYSTEM: SYSGEN 
SYSGEN> LOAD DMAO: [YOUR.DIRECTORY] YRDRIVER.EXE 
SYSGEN> SHOW /DEVICE=YRDRIVER 


oe Dev___DDB CRB IDB Unit__UCB____ 
YRDRIVER 80060E50 80061070 
SYSGEN> CONNECT YR /ADAP=3/VEC=%0274/CSR=%0776240 


SYSGEN> SHOW /DEVICE=YRDRIVER 


__Driver____ Start____FEnd__._Dev___DDB...__ CRB___ IDB____ Unit__UCB 


YRDRIVER  80060E50 80061070 
YRA 8005FDCO 80060B70 8005FE00 


0 80060BB0 
SYSGEN> EXIT 





Inserting Breakpoints in Driver Source Code 


The SYSGEN command CONNECT calls controller initialization and unit 
initialization routines. To begin debugging the driver, you should ensure that 
the kernel-mode debugging utility XDELTA gains control of the driver before 
these routines execute. This is accomplished by placing one or more calls 

to the special system routine INI$BRK within the source code of either the 
controller or unit initialization routine. To call INI$BRK, use the following 
instruction: 


JSB G* INI$BRK 
_ The INI$BRK routine contains two instructions: 


BPT 
RSB 


When the processor executes the BPT instruction, XDELTA gains control and 
reports the address of the breakpoint: 


1 BRK AT nnnnnnnn 


You can use INI$BRK as a debugging tool and place calls to it within any part 
of the driver source code. 


To determine the last driver PC before the breakpoint, examine the kernel 
stack. The stack register is register RE (hexadecimal format): 


RE/address /address 


Display RE to find the address of the top of the stack. Another display 
command (/) reveals the contents of the top of the stack, which should be 
the return address to the driver that called INI$BRK. 
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16.5 Calculating the Base of Driver Code 


Before you debug the driver, it is a good idea to calculate the base address of 
driver code, as follows: 


1 Run SYSGEN and issue the SHOW/DEVICE command. The resulting 
display lists the location in nonpaged pool at which SYSGEN loaded the 
driver. 


2 Consult the loadmap for the driver (obtained at driver link time). Driver 
code resides in two program sections (PSECTs): 


$$$ 105_PROLOGUE driver prologue table 
$$$ 115_DRIVER driver code 


The locations given in the driver code listing are offsets from $$$115_ 
DRIVER. Thus, you can calculate the base address of the driver by adding 
the address at which the driver was loaded to the offset associated with 
the PSECT $$$115_DRIVER shown in the map. 


If you do not have the loadmap, consult the driver prologue table in the 
driver listing. Look for the address of DPT_STORE_END, which generates a 
2-byte entry that terminates the DPT. To get the base address of driver code, 
add the address of DPT_STORE_END + 2 to the address at which the driver 
was loaded. You can set an XDELTA base register to the base of driver code; 
Section 16.8 describes this procedure. 





16.6 Requesting an XDELTA Software Interrupt 


Once the controller and unit initialization routines complete execution, 
you will need to set breakpoints in order to debug the driver. You can set 
a breakpoint in the driver source code by inserting calls to INI$BRK, as 
described in Section 16.4. 


Note that, in a VMS multiprocessing system, only one processor can be in 
XDELTA at a time. If a processor encounters a breakpoint while another 
processor is in XDELTA, it too must wait until the current processor exits 
from XDELTA. When it does, this processor again executes the instruction 
that caused it to attempt to enter XDELTA. If the processor previously in 
XDELTA did not delete the breakpoint, this processor now enters XDELTA. 
If the processor previously in XDELTA did remove the breakpoint, this 
processor does not enter XDELTA. 


You can also invoke XDELTA to set breakpoints interactively by requesting 
an XDELTA software interrupt. 


The procedures described in Table 16-3 issue a software interrupt to a single 
processor at IPL 14. 


On the processor requesting the XDELTA interrupt, the interrupt service 
routine at IPL 14 handles the interrupt by calling the routine INI$BRK, which 
in turn executes the first XDELTA breakpoint. XDELTA then issues this 
message: 


1 BRK AT nnnnnnnn 
address/NOP 
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In a VMS multiprocessing system, if another processor attempts to enter 
XDELTA at this time, it must wait until the processor currently in XDELTA 
exits. 


Table 16-3 Requesting an XDELTA Software Interrupt 


System Boot Commands 


VAX 8530/8550/8700/8800/8830/8840' 
VAX 6200 Series” $ 
>>>HALT 


>>>D/I 14 E 
>>>C 


VAX 8600/8650/86707 


$ 
>>>HALT 
>>>D/I 14 E 
>>>C 
VAX 8200/8250/8300/8350 
VAX-11/750 $ 
VAX-11/730 >>>D/I 14 E 
VAX-11/7257 >>>C 
VAX-11/780 
VAX-—11/785 $ 
>>>HALT 
>>>DEPOSIT/I 14 E 
>>>CONTINUE 
MicroVAX 3600 Series Press and release the HALT 
MicroVAX Il button on the CPU control 
MicroVAX I? panel, or press the BREAK 


key (if enabled) on the console 
terminal. Then issue these 
commands: 


>>>D/I 14 E 
>>>C 


'Note that the console prompt for the VAX 8830 and 8840 systems is PS-CIO-O> and 
not >>>. 


2These VAX systems accept only 1-character console commands. 


16.7 Examining the Vector-Jump Table 
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To gain familiarity with the I/O database, you might wish to look for the 
address of the location in the channel request block that contains a JSB 
instruction to the driver’s interrupt service routine. You can do this at a 
controller initialization breakpoint because one of the inputs is the IDB 
address. The procedures for locating the driver interrupt service routine on 
non-direct-vector and direct-vector adapters follow. 
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Non- Direct-Vector Procedure 


R5/IDB-address Q+10/ADP-address 
Q+10/vector-table-address 
Qt+tvector-address-in-hex/address-of- JSB-instruction-in-CRB 
Q! JSB-instruction 


Direct-Vector Procedure 


R5/IDB-address Q+10/ADP-address 
Q+10/vector-table-address 
Q+vector-address-in-hex+2/address-of-JSB-instruction-in-CRB 
Q! JSB-instruction 


Finding the address of the driver’s interrupt service routine at the expected 
vector does not guarantee that an interrupt from the device will dispatch to 
the driver’s interrupt service routine. If the device’s physical vector is set to 
some other address, an interrupt from the device can dispatch to some other 
interrupt service routine, or dispatch to an unassigned vector. 


See the SYSGEN device table shown in Table 15-2 for a list of vectors. 
Consult DIGITAL field service for help with any ere similar to the one 
described above. 





16.8 Setting an XDELTA Base Register 


During a driver debugging session, you can use an XDELTA relocation register 
as a base from which to examine driver code and set breakpoints within the 
driver. Use one of the methods outlined in Section 16.5 to determine the base 
address of driver code, then set a relocation register by issuing the following 
command: 


driver-base-address,0;X {RET 


This command sets relocation register XO to the base of driver code. Now you 
can examine offsets into the code using XO as a base: 


XO + offset/nnnnnnnn 
or 
XO + offset!instruction 


XDELTA also uses the base register to display address values in the base 
register plus offset format. Suppose, for example, that your driver contains 
the following code:. 


50 81 90 O0OD3 132 10$: MOVB  (R1)+,RO 
10 13 OOD6 133 BEQL 20$ 
20 50 91 OOD8 134 CMPB RO,#*A/ / 
F6 19 OODB 135 - BLSS  10$ 
7A 8F 50 91 OODD 136 CMPB RO,#*A/Z/ 
FO 14 OOE1 137 BGTR 10$ 
82 50 90 OOE3 138 MOVB RO, (R2)+ 
EB 11 OOE6 139 BRB 10$ 
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If base register 0 contains the base address of your driver, the following 
XDELTA dialogue is possible: 


X0+D3,X0+E6!X0+D3/MOVB (R1)+,RO 
X0+D6/BEQL XO+E8 

X0+D8/CMPB RO, #20 
X0+DB/BLSS X0+D3 

X0+DD/CMPB RO,#7A 
X0+E1/BGTR X0+D3 

X0+E3/MOVB RO, (R2) + 
X0+E6/BRB X0+D3 


To set breakpoints in driver code, use the following command: 
XO + offset;B 


To display a driver instruction and set a breakpoint, add the instruction’s 
offset to the base register. For example: 


X0+1C! instruction  .;B 


The last XDELTA command sets a breakpoint at the displayed location. 
See Section 16.10 or the VMS Delta/XDelta Utility Manual for a detailed 
discussion of XDELTA commands. 





16.9 Examining the UCB, IRP, or PSL 


In addition to using XDELTA to debug drivers, you can also examine the 
contents of the UCB and the associated IRP. 


It is also useful to examine the contents of the PSL at the time of a system 
failure. The PSL, for example, indicates the IPL at the time. When the system 
fails it prints the PSL and other register contents on the console terminal. 


While the system is running, the following command can be used to examine 
the PSL in XDELTA: 


RF+4/ 


The PSL location is stored in the longword following the PC. 





16.10 XDELTA Commands 


Table 16—4 summarizes XDELTA commands. The sections that follow this 
table describe the commands. 


Table 16-4 XDELTA Command Summary 
Command _— Function 


Set Display Mode 


{B Set byte mode 
[W Set word mode 
[L Set longword mode 
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Table 16—4 (Cont.) XDELTA Command Summary 


Command _ Function 





Set Display Mode 


{I Set instruction mode 
. Set ASCII mode 


Set and Proceed from Breakpoint 


a Proceed from breakpoint 
7B Set/clear/display breakpoint 


Open, Examine, and Close Location 


Open location (display contents in current mode) 
Open location (display contents as instructions) 
Close current location 


Close current location; open next 


|=} |x] ~ ™ 
a) 
ise) 


Open location specified by current value 


m 
icp) 
(2) 


Display previous location 


Deposit in Location 


‘string’ Deposit string at current location, autoincrementing the current 
location symbol (.). Every carriage-return and line-feed character 
typed will be stored. An apostrophe terminates the string. 


Step, Set Location, and Execute Code 


S Execute one instruction, step into subroutine call 

O Execute one instruction, step over subroutine call (on CALLx, JSB, 
or BSBx instruction) 

iG Go to location and proceed 

iE Execute command string at location 


Special Symbols 


; Field separator 
0] Last quantity displayed 


= Display value of expression; set Q 
Xn Base register n 

ix Set base register 

Rn Register n 

Pn Processor register n 
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Table 16—4 (Cont.) XDELTA Command Summary 


Command Function 


Special Symbols 

G Add *X80000000 to subsequent or preceding value 

H Add *“X7FFEOOOO to subsequent or preceding value 
Current location 


Operators 

+ Add 

- Subtract 
space Add 

. Multiply 
@ Shift 

% Divide 


Miscellaneous 


iL List names and locations of loaded executive images 


16.10.1 Values and Expressions 
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All numeric values are interpreted in hexadecimal radix. Expressions are 
strings of alternating values and binary operators, where the first and last 
items in the string are always values, as in the following example: 


G4A32 + 24 - . 


XDELTA evaluates expressions from left to right with no precedence, and 
ignores trailing operators. To display the value of an expression, use the 
XDELTA Show Value (=) command, as follows: 


Syntax 
expression=value-of-expression 


Type an expression followed by an equal sign (=). The expression can be 
composed of a series of values and operators from the set of operators listed 
in the command summary. XDELTA shows the value of the expression 
according to the current display data type. The last quantity (Q) is set to the 
value of the computed expression. 


16.10.2 Special Symbols 


16.10.2.1 


16.10.2.2 
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XDELTA defines the following special symbols: 


Current location; set by slash (/), exclamation point (!) and TAB 
operations. 


Q Last quantity displayed; you can also change this value by using the 
Show Value (=) command described in Section 16.10. 1. 


XO—XF Base registers; used for remembering values. Set base registers 
by means of the Set Base Register command (;X) described in 
Sections 16.8 and 16.10.2.3. XDELTA, by default, stores special 
values in base registers X4 and X5 that help reference the process 
control block of the current process (see Section 16.10.2.1). Also, 
XDELTA initializes XE and XF with special commands that help 
reference page-frame numbers, as described in Section 16.10.2.2. 


RO-RF General register names. 

PO-Pnn internal processor registers. 

RF+4 PSL. 

G “*X80000000; prefix for system space addresses; for example, G2E 
is equivalent to “X8OO0002E. 

H *X7FFEOOOO; prefix for control region prefix; for example, H2E is 


equivalent to “X7FFEOO2E. 


Stored Base Registers 

XDELTA defines two base registers useful in system debugging: X4 and X5. 
Base register X4 contains the address of the location that contains the address 
of the PCB of the current process on the current processor. Base register X5 
corresponds to the global symbol SCH$GL_PCBVEC, which contains the 
starting address of the list of PCB slots. 


Stored Command Strings 

XDELTA contains two predefined command strings whose addresses are 
contained in base registers XE and XF. You can use these commands during 
general system debugging as well as driver debugging; they perform the 
following functions: 


XE Use the value of base register XO as a page-frame number and display 
the PFN database for that page 
XF Set base register XO to the value (PFN) in RO and perform the same 


function as XE 


You must initialize the stored commands to set the relocation registers they 
use (X6 through XD). Issue the following commands: 


XE;E 
XF;E 


After executing these commands, you can use the commands stored in XE 
and XF to obtain the following information about a page-frame number: 


e Specified physical page number (PFN) 
e PEN state 
e PEN type 


e =69PFN reference count 
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16.10.2.3 


e PEN backward link/working set list index 
e PEN forward link/share count 

e Page-table entry (PTE) pointer to PFN 

e PEN backing store address 


e Virtual block number in process swap image 


Setting Base Registers 
Syntax 


address-expression,n;X 


Type an expression followed by a comma (,), a single digit between 0 and D 
(hexadecimal), a semicolon (;), and the letter X. XDELTA assigns the specified 
expression to the base register selected by n. XDELTA confirms that the base 
register is set by displaying the value deposited in the base register. 


Whenever XDELTA displays an address located close to an address stored in 
a base register, XDELTA displays the base register identifier (Xn), followed by 
an offset that gives the address’s location in relation to the address stored in 
the base register. For example, if base register 2 (X2) contains 800D046A and 
the address XDELTA needs to display is 800D052E, XDELTA displays X2+C4. 
XDELTA computes relative addresses for opened or displayed locations and 
addresses that are instruction operands. 


XDELTA displays an address in base register plus offset format to a distance 
of 800;¢ from the base register. If the address falls outside this range, 
XDELTA displays it as a hexadecimal value. 


16.10.3 Display Names and Locations of Loaded Executive Images 


16.10.4 Set Display Mode 
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Syntax 
7 


Use the ;L command to list the names and locations of the loaded modules 
of the VMS executive. If you issue the ;L command before all the executive 
images are loaded (for example, at an XDELTA initial breakpoint), only those 
images that have been loaded will be displayed. 


Syntax 


[B Byte width 

[W Word width 

[L | Longword width 

{I Instruction display (using longword width) 
ASCII display (using current width) 
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Type a left square bracket ([) followed by one of the letters B, W, or L to 
change the current display width to byte, word, or longword respectively. 
The default value is longword. The setting remains in effect until another 
display mode control command is given. For example, the following 
command displays the least significant byte contained at the specified address 
and deposits the new value to that byte only. 


address-expression [B/ old-value new-value 


Type a left square bracket ({) followed by the letter I to change the current 
display mode to instruction format. This command is equivalent to the 
exclamation point (!) command and, similarly, is canceled by typing a slash 
(/) or a quotation mark ("). Instruction mode sets display mode storage 
units to longword values. For an example of an instruction display, see 
Section 16.8. 


You can display contents of memory locations in ASCII characters by typing 
an address expression followed by a quotation mark ("). 


address-expression" old-value-in-ASCII 
Pressing LINE FEED displays the next location in ASCII. 


The display mode remains set to ASCII until the next slash (/) or exclamation 
point (!) command. At this point, the display mode reverts to hexadecimal. 
The width remains unchanged. 


16.10.5 Open, Examine, and Close Location 


16.10.5.1 


XDELTA provides the commands described in the following sections to open, 
examine, and close the specified memory locations. 


Open and Display Value Command 
Syntax 


address-expression/old-value [new-value-expression] 


Type an address expression followed by a slash (/) character. XDELTA 
displays the contents of the location (old-value above), followed by a space 
character. You can change the value at the location by typing a new value 
and then pressing RETURN. If you press RETURN without preceding it with 
a value, the old contents remain unchanged. 


The display and the value deposited default to longword hexadecimal values. 
The length can be changed to byte or word with the set mode commands. 


A slash preceded by a null address expression uses the displayed value (Q) 
as the address value. This feature is convenient for following address linked 
chains, as follows: 


address-expression/old-value /old-value /old-value 
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16.10.5.2 


16.10.5.3 


16.10.5.4 


Display Instruction Command 
Syntax 


address-expression! decoded-instruction 


Type an address expression followed by an exclamation point (!). XDELTA 
displays the contents of memory as a VAX MACRO instruction starting with 
the address you specify. 


XDELTA does not make any distinction between reasonable and unreasonable 
instructions or instruction streams; the decoding always begins at the specified 
address. The display instruction command does not allow you to modify the 
displayed location. The command sets a flag that causes subsequent close and 
display next or indirect location commands to perform instruction decoding. 
You can reset the flag with the open and display value command. 


Whenever an address appears as an instruction operand, XDELTA sets the 
last quantity displayed (Q) to that address. XDELTA changes Q only for 
operands that use program counter or branch displacement addressing modes; 
Q is not altered for literal and register addressing modes. This feature is 
useful for following branches, as follows: 


address-expression!BRW address-2 !instruction-at-address-2 


Close and Display Next Location Command 
Syntax 


address/old-value 


Press LINE FEED. XDELTA closes the current open location, then opens and 
displays the value in the next location, according to the current display mode. 


If instruction display is the current mode, XDELTA does not deposit a value in 
the open location. The next location is the first location after the instruction 
currently displayed. If value display is the current mode, you can deposit 

a value into the open location. In this case, the next location is the current 
location, incremented by the current data width (byte, word, or longword). 


Display Range Command 
Syntax 


start-addr-expression, end-addr-expression/contents-of-start 
or 
start-addr-expression, end-addr-expression! contents-of-start 


Type two address expressions separated by a comma and followed by a 
slash (/) or exclamation point (!) character. XDELTA displays the range 

of addresses, using the specified display mode (value or instruction). If 

you specify instruction display, XDELTA decodes one or more instructions. 
Otherwise, XDELTA displays the contents of each location in the current data 
type (byte, word, or longword). 


16.10.5.5 


16.10.5.6 


16.10.6 Breakpoints 


16.10.6.1 


Debugging a Device Driver 
16.10 XDELTA Commands 


Indirect Command 
Syntax 


address/old-value 


_ Press TAB. XDELTA uses the last quantity displayed (Q) as an address and 


displays that address and its contents using the current display mode. This 
command opens locations in the same way as the slash (/) and exclamation 
point (!) commands, but prints the information on a new line and displays 
the address value before showing the address’s contents. 


Display Previous Location Command 
Syntax 


address/old-value 


Press ESC. Unless the current display mode is instruction, XDELTA decreases 
the location counter by the current data width, and displays the contents of 
the resulting location using the current data width and type. This command 
is ignored in instruction display mode. 


XDELTA uses the following commands to set and clear breakpoints, display 
a list of set breakpoints, continue from a breakpoint, and set a complex 
breakpoint. 


Setting Breakpoints 
Syntax 


address-expression;B 


Type an address followed by a semicolon (;) and the letter B, then press 
RETURN. XDELTA sets a breakpoint at the specified location and assigns it 
the first available breakpoint number. 


Alternate syntax: 
address-expression,n;B 


Type an address followed by a comma, a single digit between 2 and 8, 

a semicolon (;), the letter B, and then press RETURN. XDELTA sets a 
breakpoint at the specified location and assigns it the specified breakpoint 
number. Breakpoint 1 is reserved for INI$BRK. 


Before XDELTA executes the instruction as a breakpoint, it suspends normal 
instruction processing, sets a flag that causes subsequent close and display 
next or indirect location commands to perform instruction decoding, and 
displays the following message: 


n BRK at address 
address/decoded-instruction 


You can now enter XDELTA commands. You can reset the flag that controls 
instruction display mode by issuing the open and display value command. 
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16.10.6.2 


16.10.6.3 


16.10.6.4 


16.10.6.5 


Clearing Breakpoints 
Syntax 


0,n;B 


Type zero (0) followed by a comma, a single digit between 2 and 8, a 
semicolon (;), the letter B, and then press RETURN. XDELTA clears the 
specified breakpoint. Never clear breakpoint 1. 


Displaying Breakpoint List 


Syntax 
;B 


Type a semicolon (;) followed by the letter B. XDELTA shows the current 
settings of all breakpoints. For each breakpoint, XDELTA displays the 
following information: 


¢ Breakpoint number 
e Address at which the breakpoint is set 
e Display address (for complex breakpoints; see Section 16.10.6.5) 


¢ Command string address (for complex breakpoints) 


Proceeding from Breakpoints 


Syntax 
;P 


Type a semicolon (;) followed by the letter P, and then press RETURN. 
XDELTA continues executing at the current PC. 


Setting Complex Breakpoints 
Syntax 


address-expression,n,display-addr-expression, command-string-address ;B 


Type an address expression followed by a comma, a single digit between 

2 and 8, another address expression, and the address of a command string. 
The first address is the breakpoint address; the digit equals the breakpoint 
number. XDELTA shows the contents of the display address in the current 
display mode when the breakpoint is reached. The command string address 
specified in the last command parameter executes after automatic display. 


16.10.7 Step, Set Location, and Execute Instruction Commands 
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16.10.7.1 


The following XDELTA commands enable you to step through and execute 
driver code. 


Loading PC and Continuing 
Syntax 
address-expression;G 


Type an address, a semicolon, and G, then press RETURN. XDELTA loads 
the address into PC and continues executing at the new PC. 
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16.10.7.2 Execute Instruction and Step Command 
Syntax 


S) 


Type an S. XDELTA causes one instruction to be executed, then displays the 
address of the next instruction and decodes that instruction. 


This command also sets a flag that causes subsequent close and display next 
or indirect location commands to perform instruction decoding. The open and 
display value command resets the flag. 


If the next instruction is BSBB, BSBW, JSB, CALLG, or CALLS, this command 
steps into the subroutine and displays the first instruction within the routine. 


16.10.7.3 Step Instruction Over Subroutine Command 
Syntax 


0 


Type an O. XDELTA causes one instruction to be executed, then displays the 
address of the next instruction and decodes that instruction. 


This command also sets a flag that causes subsequent close and display next 
or indirect location commands to perform instruction decoding. The open and 
display value command resets the flag. 


If the next instruction is BSBB, BSBW, JSB, CALLG or CALLS, XDELTA 
executes the entire subroutine and displays the instruction that immediately 
follows the subroutine call; this command steps over subroutines. 


16.10.8 Execute String Command 
Syntax 
address-expression;E 


Type an address expression followed by a semicolon, the letter E, then 
press RETURN. This command executes the ASCII commands found at the 
specified address expression. If you terminate the ASCII commands with 

a semicolon followed by the letter P, XDELTA will proceed with program 
execution. If you terminate the string with null (1 byte of 0), XDELTA waits 
for a new command. 


To create command strings, open the address of the start of the string and 
deposit ASCII text as follows: 


address/old-contents 'XDELTA-command' [RET 


You can use any XDELTA command, including RETURN, LINE FEED, and 
TAB. 


To terminate the string with a null, follow the above command with 
./old-contents 0 


You can deposit command strings into nonpaged system patch space. To 
determine the size of patch space and its starting address, locate the symbol 
PAT$A_NONPGBD in the system map file (SYS$SYSTEM:SYS.MAP). This 
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symbol contains a descriptor of the address and size of patch space remaining 
in the system, as follows: 


PAT$A_NONPGD: : 


. LONG size-in-bytes 
. LONG patch-space-start-address 


You can also preassemble command strings with your experimental driver. 
Locate the addresses of these strings as you would any other address within 
your driver. 





16.11 Guidelines for Debugging Device Drivers 


16.11.1 Opening Device R 


The following sections discuss errors commonly made during debugging 
sessions and describe additional debugging techniques. 


egisters in XDELTA 


References to 16-bit device registers must be word instructions; references to 
8-bit device registers must be byte instructions. These restrictions apply to 
the XDELTA EXAMINE command; therefore, be sure to set the correct mode 
control before examining device registers. For example, if the address of the 
device CSR is in R4, give the following command: 


R4/csr_address [W/csr_contents 


16.11.2 Adjusting the Device Timeout Value 


16.11.3 XDELTA and Syst 
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When single-stepping through driver code using XDELTA, it may be necessary 
to adjust the device’s timeout value (as specified in the WFIKPCH or 
WFIRLCH macro) so that it is large enough to keep the device from timing 
out. When the driver debugging is complete, this value should be reset to a 
reasonable length of time. 


em Failures 


Driver errors can cause the operating system to suspend activity in such a 
way that you cannot invoke XDELTA. In this case, the only recourse is to 
induce a system failure. Follow the procedure described in the VMS System 
Dump Analyzer Utility Manual; the system will signal a fatal bugcheck. 


To gain control in XDELTA following a fatal bugcheck, stop in SYSBOOT 
while initializing the system and clear the BUGREBOOT system parameter. 
The system will stop in XDELTA, thereby allowing you to examine the device 
UCB and other driver data to determine the driver error. 


Another, more thorough, way to determine the cause of a system failure is 
to leave the BUGREBOOT system parameter set, allow the system to reboot, 
and then invoke the System Dump Analyzer (SDA) Utility to examine the 
condition of the I/O data structures at the time of the fatal bugcheck. The 
VMS System Dump Analyzer Utility Manual provides detailed information on 
fatal bugcheck stack format and how SDA can help debug a device driver. 
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16.12 Common Driver Errors 


This section describes errors commonly made in drivers. 


16.12.1 References to System Addresses 


References by drivers to system addresses within the executive must use 
general addressing (G*) mode. For example, use 


JSB. G* INIS$BRK 


16.12.2 Incorrect References to Device Registers 


A common driver error is to access a nonexistent device register or to 

access the correct register with an instruction using incorrect length. On 
VAX systems that use direct-vector interrupts, these references cause a fatal 
machine check exception. On VAX systems using non-direct-vector interrupts, 
these references cause a UNIBUS adapter error interrupt. The system logs the 
adapter error and continues. 


In many cases, the saved PC on the stack is the address of the instruction that 
caused the error. In other cases (for example, when the offending instruction 
is executed at IPL 31), the saved PC is not the address of this instruction 

but an address some number of instructions later, when the system actually 
services the interrupt. 


16.12.3 Destroying Register Contents 


Because the driver frequently calls VMS I/O routines, you must be careful 

to anticipate the register usage of these routines. Most VMS common I/O 
support routines use RO through R3 freely. A frequent driver bug is to load a 
value into R3 and expect to find it intact after a call to allocate or load adapter 
resources. 


Other VMS I/O routines write into R4. In some cases, the use of R4 is 
obvious; for example, IOC$SREQSCHANL writes the device’s CRB address 
into R4. In other cases, you might not anticipate the use of R4. 


For example, EXE$IOFORK saves the calling code’s R4 in a fork block, and 
then writes the device’s IPL into R4. Because the normal flow of events is 
that an interrupt service routine restores a driver with a JSB instruction and 
the driver then calls EXE$IOFORK which returns to the interrupt service 
routine, the instructions following the JSB in the interrupt service routine can 
only assume R35 is still untouched. The coding sequence is as follows: 


MOVQ UCB$L_FR3(R5) ,R3 ; Restore R3-R4. 
JSB @UCB$L_FPC (R5) ; Restore the driver process. 


;Between these instructions, the interrupt service routine 
;can make no assumptions about the contents of RO through R4. 


POPR #°M<RO,R1,R2,R3,R4,R5> ; Restore interrupt registers. 
REI ; Return from the interrupt. 
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16.13 Pool Checking Mechanism 


Certain system failures cannot easily be traced to a single instruction or to 

a single piece of kernel-mode code. If a device driver, for example, accesses 
memory that it has not properly allocated or continues to use memory 

that it has deallocated, a system failure can occur long after the driver has 
completed its activity. The system may crash when another operating system 
thread executes and attempts to use the corrupted data. 





Special pool checking code in the VMS memory allocation and deallocation 
modules can help isolate problems of this sort reliably and quickly. In 

a normal VMS system, this code is disabled. For a system experiencing 
frequent and inexplicable failures, you can enable pool checking by setting 
the POOLCHECK system parameter. 


When enabled, pool checking routines execute whenever pool is deallocated 
or allocated.! 


On any deallocation of pool, the routine fills the deallocated packet with 

a “free” pattern specified in the POOLCHECK system parameter. The first 
five longwords of the packet are not filled, but instead contain the following 
information: 


¢ Forward and backward links into the free list 
e Size, type, and subtype fields 
e Address of the code that deallocated the packet 


e Checksum 


On any allocation from pool, the routine verifies the checksum and ensures 
that the packet still contains the “free” pattern. If the pattern is still intact, 
the routine replaces the “free” pattern with an “allo” pattern, also specified 
in the POOLCHECK system parameter. The two patterns allow allocated, 
uninitialized pool to be distinguished from nonallocated pool. If the “free” 
pattern is not intact, the pool checking routine induces a POOLCHECK 
bugcheck, assuming that some code has modified the packet while it was on 
the free list. 


Figure 16-1 illustrates the format of the POOLCHECK system parameter. 
Figure 16—1 Format of the POOLCHECK System Parameter 


31 23 15 7 6) 


free flags 


ZK-66 18-HC 


' The pool allocation routines (EXE$ALLOCBUF, EXE$ALLOCIRP, EXE$ALONONPAGED, 
COM$DEANONPAGED, EXE$DEANONPAGED, and so on) are discussed in Appendix C. These routines are 
the only means recommended by DIGITAL for allocating pool. 
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The flags byte indicates the actions that the pool checking code should take 
whenever pool is allocated or deallocated. It also indicates the type of pool to 
be subject to checking. The following bit masks are defined: 


Bit Mask (hex) Action 
1 At deallocation, fill variable pool packets with free pattern. 
2 At allocation, check packets for free pattern and, if the 


pattern is intact, fill with allo pattern. If not, induce 
POOLCHECK bugcheck. 


4 At deallocation, fill SRPs with free pattern. 
8 At deallocation, fill IRPs with free pattern. 
10 At deallocation, fill LRPs with free pattern. 
80 At deallocation, fill P1-space addresses with free pattern. 


The free byte indicates the character to be inserted in a packet (except for its 
header) when it is deallocated to free pool. 


The allo byte indicates the character to be inserted in a packet (if bit 2 of the 
flags byte is set) when it is allocated. 


It is possible that, when first enabled on a system, the pool checking 
mechanism will discover specific violations of pool allocation and deallocation 
protocol. In investigating subsequent crashes using SDA, you should first 
check the value of the global longword EXE$GL_POOLCHECK to determine 
whether pool checking has been enabled and, if so, which packets it has been 
enabled for and which patterns it is using. 


One of the results of the pool checking mechanism is the occurrence of a fatal 
system bugcheck such as INVEXCEPTN, SSRVEXCEPT, or FATALEXCPTN 
whenever kernel-mode code attempts to use an address in free pool. When 
these exceptions signal an access violation and the free pattern appears as the 
violating address in the exception’s signal array, the exception PC has been 
caught in the process of using deallocated pool. 


The POOLCHECK bugcheck is explicitly generated by the pool checking 
mechanism whenever it determines that a pool packet has been corrupted 
while on the free queue. When a POOLCHECK bugcheck occurs, you can 
obtain information about the crash from the contents of general registers as 
well as from the pool packet itself. At the time of the crash, the following 
registers contain relevant information: 


Register Contents 

RO Allocation (allo) pattern 

R1 Deallocation (free) pattern 

R2 Address of packet being allocated 

R3 Number of longwords remaining in packet to be 
checked 

R4 Address in packet where the pool checking code 


discovered corrupted pattern 
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Register Contents 
R5 Checksum, computed as the sum of the address of 


the packet, the deallocation pattern, the third and 
fourth longwords of the packet, and a longword 
within the system boot time quadword (EXE$GQ_ 
BOOTIME) 


Because the address of the packet is in R2, you can attempt to format R2 to 
see what type of structure the pool is being allocated for. The following SDA 
commands accomplish this: 


SDA> READ SYS$SYSTEM:SYSDEF .STB 
SDA> FORMAT @R2 


If this does not identify the structure, you may obtain some information from 
the packet itself, as pictured in Figure 16-2. 


Figure 16—2 Poisoned Pool Packet 


| poison pattern (RO minus 20) | 


ZK-66 19-HC 












To determine what code may have corrupted the packet, it may be helpful to 
examine the contents of R4 (the address at which the pool checking routine 
found a corrupted pattern). If this address contains an address, it is a fair 
assumption that code that uses that address placed it there. 


In addition, the routine that deallocated the packet may be a likely suspect. 
Frequently, pool is corrupted by a device driver that deallocates pool and later 
attempts to use the pool that it has deallocated. 





16.14 Detecting Driver Problems in a Multiprocessing System 
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When testing a new driver that has been designed to run in a VMS 
multiprocessing environment, it is a good idea to ensure that the system in 
which the driver is being tested is running the full-checking synchronization 
image. You can cause the full-checking synchronization image to be loaded 
at boot time on either a VAX uniprocessing system or multiprocessing system 
by the appropriate setting of the MULTIPROCESSING system parameter, as 
listed in Table 16-5. 
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Table 16—5 Settings of MULTIPROCESSING System Parameter 


Value 


0 


Result 


Loads uniprocessing synchronization image for any hardware 
configuration. 


Loads full-checking synchronization image and sets multiprocessing- 
enabled bit (SMP$V_ENABLED in SMP$GL_FLAGS) if the 
hardware configuration is capable of multiprocessing and two 

or more processors are available; otherwise, loads uniprocessing 
synchronization image. This is the default value. 


Loads full-checking synchronization image and sets multiprocessing- 
enabled bit regardless of the hardware configuration. 


Loads streamlined synchronization image and sets multiprocessing- 
enabled bit if the hardware configuration is capable of multiprocessing 
and two or more processors are available; otherwise, loads 
uniprocessing synchronization image. 


In a processing environment with the full-checking synchronization image 
loaded, violation of spin lock synchronization by a device driver will produce 
the bugchecks described in Table 16-6. 


Table 16—6 Bugchecks Produced by Full-Checking Multiprocessing 


SPLIPLHIGH A processor has attempted to acquire a spin lock at an IPL 


higher than the IPL associated with spin lock synchronization 
(SPL$B_IPL). SMP$ACQUIRE (called by the LOCK and FORKLOCK 
macros with condition=-NOSETIPL not specified) signals this 
bugcheck. 


A processor has attempted to acquire a device lock—not 
already owned by the acquiring processor—at an IPL higher than 
the IPL associated with device lock synchronization (SPL$B_ 
IPL). SMPSACOQUIREL (called by the DEVICELOCK macro with 
condition=NOSETIPL not set) signals this bugcheck. 


SPLIPLLOW A processor has attempted to conditionally or unconditionally 


release a spin lock or device lock at an IPL lower than the 

IPL at which it originally acquired it. SMPSRELEASE and 
SMP$RESTORE (called by the UNLOCK and FORKUNLOCK 
macros) and SMP$RELEASEL or SMP$RESTOREL (called by the 
DEVICEUNLOCK macro) signal this bugcheck. 


SPLACQERR A processor has attempted to acquire a spin lock while holding 


SPLRELERR 


a higher ranked spin lock. SMP$ACQUIRE, SMP$ACQUIREL, 
and SMP$ACONOIPL (called by the LOCK, FORKLOCK, and 
DEVICELOCK macros) signal this bugcheck. 


An attempt has been made to completely release a spin lock 
not owned by the releasing processor. SMP$RELEASE and 
SMP$RELEASEL (called by the UNLOCK, FORKUNLOCK, and 
DEVICEUNLOCK macros) signal this bugcheck. 


16-25 


Debugging a Device Driver | 
16.14 Detecting Driver Problems in a Multiprocessing System 


16-26 


Table 16—6 (Cont.) Bugchecks Produced by Full-Checking 


Multiprocessing 


SPLRSTERR An attempt has been made to conditionally release a spin lock 


not owned by the releasing processor. SMP$RESTORE and 
SMP$RESTOREL (called by the UNLOCK, FORKUNLOCK, and 
DEVICEUNLOCK macros when condition=RESTORE is specified) 
signal this bugcheck. 


An examination of the crash dump resulting from any of these bugchecks can 
help locate the cause of the crash. Enter the System Dump Analyzer (SDA) 
and perform the following steps: 


1 


Issue the following command: 
SDA> READ/EXECUTIVE SYS$LOADABLE_IMAGES 


This command generates the symbols that correspond to locations in 
the loadable images that are part of the VMS executive. These symbols 
facilitate the interpretation of addresses that appear in the stacks and 
other SDA displays. 


Issue the following command: 
SDA> SHOW STACK 


Trace through the current stack to determine what activities on the 
processor led to the acquisition or release of the spin lock. Start at high 
stack addresses and work towards low addresses, identifying everything 
on the stack, or as much of it as required to decipher what is going on. 


Issue the following command: 
SDA> SHOW SPINLOCK/FULL/ADDR=@RO 


This command produces a display of information about the spin lock the 
executing code was trying to acquire or release, a list of PCs indicating 
the addresses of the latest eight acquirers or releasers of the lock, plus the 
PC of the last unconditional release of a set of multiply nested spin lock 
acquisitions. Note the acquisition IPL and the rank of the spin lock. 


To decipher SPLIPLLO and SPLIPLHI bugchecks, compare the IPL at 
which the system was running at the time of the crash to that shown 
in the SHOW SPINLOCK display as required for acquisition of the spin 
lock. . 


To decipher SPLACQERR, SPLRSTERR, and SPLRELERR bugchecks, 
issue the following command: 


SDA> SHOW SPINLOCK/OWNED 


In the case of SPLACQERR bugchecks, compare the rank of the spin lock 
being sought with that of the currently owned spin locks. 


In the case of SPLRSTERR and SPLRELERR bugchecks, determine 
whether the releasing processing in fact did not own the spin lock it is 
attempting to release. 


Standard drivers seldom release spin locks and fork locks. When they do, 
they should be careful to use the condition=-RESTORE argument to the 
UNLOCK and FORKUNLOCK macros when it is likely that the driver code is 
executing at the behest of other code interested in retaining the lock. 
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One error of which driver writers should be wary concerns the unconditional 
release of a spin lock or fork lock for which there exist multiple, nested 
acquisitions. When multiple acquisitions of a spin lock accumulate for 

a processor, and one of the intermediate acquirers performs an explicit 
release of that lock, all ownership of the lock by that processor is entirely 
and immediately relinquished. If at least one of the original acquisition 
threads still expects the lock to be held when that thread regains control, 
system synchronization is broken. Moreover, when the original thread that 
acquired the lock itself attempts to release the lock, the system crashes with 
an SPLRELERR because the processor no longer owns the lock being released. 


If few attempts have subsequently been made by the processor to obtain or 
release spin locks, you should be able to find the PC of the code that last 
unconditionally released the spin lock in question in SHOW SPINLOCKS 
/FULL/ADDRESS=@R0 display. Issue the SDA command EXAMINE/INST 
for each of the PCs in the display, from the top to the bottom, to determine 
the recent history of the lock. 
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This chapter describes details of the implementation of the VMS terminal 
driver. The VMS terminal driver consists of two pieces: the terminal port 
driver and the terminal class driver. These two pieces of code, when bound 
together within the unit control block (UCB), form a single device-dependent 
driver that implements the VMS terminal services. 


TTDRIVER.EXE, the VMS terminal class driver, handles the device- 
independent functions and tasks. For example, it contains code that enables 
command line editing on many different types of terminals. The port drivers 
manage those functions and tasks that depend on the device’s hardware 
configuration. For example, the port driver for a particular type of terminal 
controller performs the actual transmission and reception of characters to and 
from that terminal controller. The port driver reserves all manipulation and 
interpretation of those characters to the class driver. Because class driver code 
supports the functions common to terminal devices, a terminal port driver can 
contain only that code needed to control a specific interface. 


There are several reasons why a new port driver may be required: 
¢ To support a new terminal controller 
¢ To implement a terminal server such as LAT11 


e To provide a pseudoterminal 


Both class drivers and port drivers adhere to the same rules as other VMS 
device drivers. They consist of the same routines and tables as standard 
drivers, and reference the same data structures. However, because a class 
driver and its port drivers must intercommunicate, they must employ a few 
additional structures and routines not required for standard VMS device 
drivers. 


The structure of the VMS terminal driver illustrates one specific approach 
to the class/port concept. The discussions that appear in this chapter relate 
only to TTDRIVER.EXE and its ports. Note that there are no supported 
methods for implementing the class/port design in a non-DIGITAL-supplied 
device driver. Moreover, the System Generation Utility (SYSGEN) provides 
no support for alternate class drivers and can only connect port drivers to 
TTDRIVER.EXE. 


The. remainder of this chapter describes how the VMS terminal class and 
port drivers are structured and how they interact. A full description of the 
functions of the VMS terminal driver appears in the VMS I/O User’s Reference 
Manual: Part I. 
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17.1 Overview 





17.1 Overview 


The terminal class driver is the device-independent part of the VMS terminal 
driver. It contains the driver’s function decision table (FDT) routines, start 
I/O routine, fork process routines, code that implements the features of the 
VMS terminal services, and the class driver service routines. 


The terminal port driver is the device-dependent piece of the VMS 

terminal driver. It contains the driver prologue table (DPT); data structure 
initialization; device, unit, and controller initialization routines; port service 
routines; interrupt service routine; and any additional device-dependent code. 
Among the port drivers included in VMS are DZDRIVER for the DZ-32 and 
DZ-11, YCDRIVER for the DMF-32 and DMZ-~32, and YFDRIVER for the 
DHU-11 and DHV-11, YIDRIVER for the DMB32, and YEDRIVER for the 
MicroVAX 2000. (See the VMS I/O User’s Reference Manual: Part I for a 
complete list of supported terminal controllers.) 





17.2 Data Structures 


17.2.1 Terminal UCB 
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There are three major data structures that define the communication between 
the port and the class drivers. These data structures are the UCB, the port 
driver vector table and the class driver vector table. To reference these 
structures, a driver must include an invocation of the STTYDEFS macro (from 
SYS$LIBRARY:LIB.MLB). The $TTYDEFS macro defines symbolic offsets for 
the following structures: 


¢ Unit control block (UCB) 

e Terminal UCB extension 

¢ Channel request block (CRB) 

e Interrupt dispatch block (IDB) 

e Port and class driver vector tables 
e =Read buffer 

e¢ Input stack 

e Item list descriptor 


e Type-ahead buffer 


A terminal UCB, as depicted in Figure 17-1, contains four sections: the 
system section (base UCB), the class driver required section, the port driver 
required section, and the port extension region.: 


The system section of the terminal driver UCB contains the pieces of the UCB 
that are present in all of the UCBs on the system. 


The class driver required section of the UCB contains fields that are needed by 
the class driver. These fields have names of the form UCB$x_TT_fieldname, 
where x denotes the field size and fieldname is the name of the field. 
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Figure 17-1 UCB Structure for Terminal Class/Port Drivers 
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‘The port driver required section of the UCB contains fields that both the class 
and port driver must access. These fields have names of the form UCB$x_ 
TP_fieldname, where x denotes the field size and fieldname is the name of 
the field. Although a port driver may not actually use all these fields, their 
presence is required. 


The terminal port extension region is defined by the terminal port driver. 
It can be any length and contain any context that the port driver needs to 
perform its duties. 


Tables A-16 and A-20 describe the fields defined within a terminal UCB, and 
Figures A-17 and A-21 illustrate their configuration. 
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17.2.2 Port Driver Vector Table 
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The port driver vector table, as depicted in Figure 17-2, is the data structure 
that allows the terminal class driver to find the port service routines. The 
vector table contains the address, relative to the beginning of the port driver, 
of each port service routine. The port driver’s controller initialization routine 
invokes the CLASS_CTRL_INIT macro, as described in Section 17.4.1.1, to 
relocate this vector table. : 


The port driver vector table is contained within the port driver itself, usually 
after the port driver's DPT. The port driver builds its vector table using the 
$VECINI, $VEC, and $VECEND macros, as described in Section 17.2.4. A 
field in the UCB, UCB$L_TT_PORT, contains the address of the port driver 
vector table. 


Port and class drivers refer to fields within the port driver vector table using 
the symbolic offsets represented in Figure 17-2. To use these offsets, they 
include an invocation of the macro $TTYDEFS (in SYS$LIBRARY:LIB.MLB). 


Figure 17—2 Port Driver Vector Table 
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17.2.3 Class Driver Vector Table 


The class driver vector table, as depicted in Figure 17-3, contains the address, 
relative to the beginning of the class driver, of each class service routine. 
The list is terminated by a longword containing zeros that indicates to the 
relocation routine where the list ends. 


At driver load time, the relative offsets are relocated to actual virtual 
addresses. The port driver’s controller initialization routine invokes the 
CLASS_CTRL_INIT macro, as described in Section 17.4.1.1, to relocate this 
vector table. The VMS terminal class driver is loaded by SYSINIT at boot 
time to allow the console terminal port driver to run. 


Figure 17—3 Class Driver Vector Table 
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The class driver vector table is contained within the class driver itself, usually 
after the class driver’s DPT. The class driver builds its vector table using the 
$VECINI, $VEC, and $VECEND macros, as described in Section 17.2.4. A 
field in the UCB, UCB$L_TT_CLASS, contains the address of the class driver 
vector table. 


17.2.4 Vector Table Generation Macros 


Port drivers use three VMS-supplied macros to build the port driver 

vector table: $VECINI, $VEC, and $VECEND. Class drivers build the 

class driver vector table using the same macros. To obtain the definitions 
for these macros, a driver must invoke the $TTYMACS macro (in 
SYS$LIBRARY:LIB.MLB). This section briefly discusses the functions of 
each of these macros. An example of their use appears in Figure 17-4 and a 
full discussion of their syntax appears in Appendix B. 
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17.2.4.1 


17.2.4.2 


17.2.4.3 


$VECINI Macro 

The $VECINI macro creates a vector table and initializes each entry with the 
address of the driver’s null entry point. Subsequent calls to the $VEC macro 
fill in selected table entries with the addresses of real entry points. 


The driver must specify the drivername and null_routine arguments to 
the $VECINI macro. The drivername argument generally contains a 2-letter 
prefix to the driver name, such as DZ or YE. The null_routine argument 
contains the address of a routine within the driver (for example DZ$NULL) 
that contains an RSB. When the class driver attempts to call the port driver 
at an entry point corresponding to an unsupported function, the port driver’s 
null routine simply returns control to the class driver. The class driver can 
then proceed to service the error. 


$VEC Macro 
The $VEC macro validates and generates a vector table entry. 


Each invocation of the $VEC macro specifies the entry argument and the 
routine argument. However, a driver need not supply the address of a 
routine for each entry in the table. The $VEC macro will construct a valid 
table regardless of how many entries are supplied. The $VEC macro accepts 
the entry names (minus the PORT_ or CLASS_ prefix) shown in Table 17-1, 
for port drivers, and Table 17-2, for class drivers. Note that a driver accesses 
the table using the symbolic offsets indicated in Figures 17-2 and 17-3. The 
$VECINI macro defines the prefix applied to the entries, which is PORT_ for 
the port vector table and CLASS_ for the class vector table. 


$VECEND Macro 

The $VECEND macro generates the longword of zeros that terminates the 
vector table and positions the location counter at label drivername$VECEND. 
It has no required arguments. 





17.3 Structure of Port and Class Drivers 
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Class and port drivers share a similar organization, as can be seen in Figures 
17-4 and 17-5. 


The vector table of each follows the driver prologue table (DPT). The driver 
specifies the address of the vector table in the vector argument to the DPTAB 
macro, which places its relative address in DPT$W_VECTOR. 


Following the vector table, and linked to the vectors by invocations of the 
$VEC macro, are a set of service routines. The balance of the driver includes 
standard driver routines and tables and driver-specific routines. 
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Figure 17—4 Port Driver Structure 
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$VECINI ZZ,ZZ$NUL 
$VEC STARTIO,ZZ$STARTIO 
$VEC RESUME,ZZ$RESUME 
$VEC ABORT,ZZ$ABORT 
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Port Specific Routines 
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Figure 17—5 Class Driver Structure 
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Class Specific Routines 
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17.3.1 Binding Class and Port Drivers 


The terminal class and port drivers are bound together to form a single, 
complete driver in the manner represented in Figure 17-6. 


The port driver’s unit initialization routine performs the binding process by 
calling the CLASS_UNIT_INIT macro. The CLASS_UNIT_INIT macro fills 
in the following UCB fields as indicated: | 


Field Contents 

UCB$L_TT_CLASS Terminal class driver’s vector table address 

UCB$L_TT_PORT Terminal port driver vector table address 

UCB$L_TT_GETNXT Address of the class driver’s get-next-character 
routine (CLASS_GETNXT) 

UCB$L_TT_PUTNXT Address of the class driver's put-next-character 
routine (CLASS_PUTNXT) 

UCB$L_DDT Address of the terminal class driver's driver dispatch 
table 


Note that, because the get-next-character and put-next-character routines are 
the most heavily used class driver routines, their addresses are stored in the 
UCB. It is therefore possible for code to issue the instruction JSB @address(R5) 
to call either routine (presuming that R5 contains the address of the UCB). 
To call other routines, the driver must first move the address of the vector 
table to a general register and issue an instruction of the form JSB @offset(Rn). 
Although a saving of one instruction does not seem significant, it can save 
one instruction per character when a driver is receiving data. 


When the port driver’s unit initialization routine completes the binding, the 
terminal class and port drivers have become one complete driver, and the 
device units are ready for I/O. 





17.4 Port Driver Routines 
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When the terminal class driver has completed a segment of device- 
independent processing of an I/O request, it calls a port routine to complete 
the device-dependent processing. The port driver contains three types of 
routines: port startup routines, port initiate routines, and port service routines. 


Table 17-1 lists the port driver routines that are part of the class/port 
interface. This section describes the functions and context of each listed 
routine. 
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Figure 17—6 Terminal Class/Port Driver Binding 
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Table 17-1 Port Driver Routines 


Routine 
Port Startup Routines 


Controller initialization 
routine 


Unit initialization routine 
Port Initiate Routines 
PORT_DISCONNECT 


PORT_DS_SET 
PORT_FDT 


PORT_FORKRET 


PORT_MAINT 


PORT_SET_LINE 
PORT_SET_MODEM 


PORT_STARTIO 


Port Service Routines 


PORT_ABORT 
PORT_CANCEL 


PORT_DMA 
PORT_RESUME 
PORT_STOP 
PORT_STOP2 
PORT_XOFF 


PORT_XON 


17.4.1 Port Startup Routines 


Port startup routines include the port driver’s controller and unit initialization 
routines. Note that, although these routines are not included in the port 

vector table, they must make calls to several class routines. They additionally 
fill the role of the equivalent initialization routines in a standard device driver, 
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as discussed in Section 11.1. 


Function 


Resets the controller and relocates the port and 
class driver vector tables 


Sets up each device unit controlled by the driver 


Notifies the port driver of the last deassign for the | 
UCB 


Outputs modem signals to a specified unit 


Performs FDT processing for device-specific 
function modifiers 


Return address in the port driver to which CLASS_ 
FORK transfers control when servicing the port 
driver's request for a fork process 


Services $QlO requests for 1O$_SETMODE 
function with the IO$M_MAINT modifier 


Changes terminal line parameters 


Informs the port that a line has been enabled for 
modem signal input transitions 


Starts output on an inactive line 


Aborts any currently active output 


Cancels internally queued operations in response 
to a $CANCEL request 


Not used; reserved to DIGITAL 
Resumes any previously stopped output 
Halts the output data stream 

Not used; reserved to DIGITAL 


Takes steps to halt an input data stream that is 
approaching its limit 


Resumes the acceptance of input data 
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17.4.1.1 Controller Initialization Routine 

The controller initialization routine is responsible for resetting the controller 
and relocating the port and class driver’s vector tables. To perform the last- 
mentioned task, the routine should invoke the CLASS_CTRL-—INIT macro, 
supplying the symbolic name of the driver prologue table (for instance, 
DZ$DPT) in the dpt argument and the address of the port driver’s vector 

- table in the vector argument. To use the CLASS_CTRL_INIT macro, the 
driver must include an invocation of the $TTYMACS definition macro (from 
SYS$LIBRARY:LIB.MLB). 


17.4.1.2 Unit Initialization Routine 
The unit initialization routine is responsible for setting up each individual 
device unit. The activities of a standard unit initialization routine include 
loading certain locations in the UCB with controller-specific data, preparing 
the hardware for input and output, and taking any action necessary to service 
a power failure. 


The unit initialization routine of a terminal port driver must additionally 
perform the following tasks: 


1 Invoke the CLASS_UNIT_INIT macro to generate the common code that 
must be executed by all terminal port driver unit initialization routines. 
This code includes the logic that binds the class and port drivers in the 
manner discussed in Section 17.3.1. Before it invokes the CLASS_UNIT_ 
INIT macro, the unit initialization routine must place the address of the 
port driver vector table in RO. 


To use the CLASS_UNIT_INIT macro, the driver must include 
an invocation of the $TTYMACS definition macro (from 
SYS$LIBRARY:LIB.MLB). 


2 Call the class service routine, CLASS_SETUP_UCB, to allow the class 
driver to reset fields in the UCB. 


3 Call the class service routine, CLASS_SET_LINE, to allow the class driver 
to reset the speed, parity, and the device-dependent bits, if necessary. 


4 If the line can run modem protocol, call the class service routine, CLASS_ 
DS_TRANS, with the transition type MODEM$C_INIT in R1. Note that, 
to use modem symbols, the port driver must invoke the $TTYMDMDEF 
macro (from SYS$LIBRARY:LIB.MLB). 


5 When a power failure occurs (UCB$V_POWER set in UCB$W_STS), call 
the class service routine, CLASS_POWERFAIL. 


6 Perform other hardware-specific functions. 


17.4.2 Port Initiate Routines 


The terminal class driver calls port initiate routines when it must initiate 
device activity and the port driver is not active. Port initiate routines can 
issue callbacks to the class driver. 


A call to a port initiate routine uses the following instruction format: 


MOVL UCB$L_TT_PORT(R5),RO ;get pointer to port vector table 
JSB @PORT_DISCONNECT (RO) ;call port disconnect routine 


Note that a port initiate routine must preserve the contents of all registers. 
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17.4.2.1 


Note: 


17.4.2.2 


17.4.2.3 


PORT_DISCONNECT 

A call to the PORT_DISCONNECT routine indicates that there are no longer 
channels associated with the device, thus notifying the port driver of the last 
deassignment for the device’s UCB. If the delete bit (UCB$V_DELMBxX) is set 
in UCBSW_DEVSTS, VMS will delete the UCB. 


As long as the device name is known to the system, broadcasts and assign 
channel requests may occur on this device. (Broadcasts, however, will not 


occur if the DEV$V_NET bit is set in UCB$L_DEVCHAR.) 


Input to the PORT_DISCONNECT routine is as follows: 

RO Flags. If bit O is set, the user requested that the UCB not be deleted 
(NOHANGUP). 

R5 Address of UCB. 


PORT_DS_SET 

The PORT_DS_SET routine sends modem signals to the specified 
unit. Masks representing modem signals are defined in $TTDEF (in 
SYS$LIBRARY:STARLET.MLB). They include the following: 


TT$M_DS_CARRIER Data channel received line signal detector 
TT$M_DS_CTS Clear to send 

TT$M_DS_DSR Data set ready 

TTS$M_DS_DTR Data terminal ready 

TT$M_DS_RING Calling indicator 

TT$M_DS_RTS Request to send 

TT$M_DS_SECREC Secondary receive 

TT$M_DS_SECTX Secondary transmit 


See the VMS I/O User’s Reference Manual: Part I for an explanation of modem 
protocol. 


Input to the PORT_DS_SET routine is as follows: 


R2 Low byte indicates signals to be activated; high byte indicates signals to 
be deactivated. 


R5 Address of UCB. 


PORT_FDT 

The terminal class driver calls the PORT_FDT routine when servicing a $QIO 
request for an IO$_TTY_PORT function. The PORT_FDT routine performs 
whatever tasks the class driver’s FDT routine would normally do to service 
the request. These tasks include checking the function-dependent parameters 
(p1 through p6), verifying access to buffers, and terminating with a call to 
EXE$QIORETURN, EXE$ABORTIO, or EXE$FINISHIO. 


The PORT_FDT routine thus allows a port driver to implement support for 
device-specific function modifiers without requiring an extension to the 
class/port interface. 


If there is no PORT_FDT routine, control will pass to the port driver’s null 
routine, which returns control to the class driver. The VMS terminal class 
driver, TTDRIVER.EXE, thereupon issues an illegal I/O function error. 


17.4.2.4 


17.4.2.5 


17.4.2.6 
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Input to the PORT_FDT routine is as follows: 


R3 Address of IRP 

R4 Address of current PCB 

R5 Address of UCB 

R6 Address of CCB 

R7 Bit number of the I/O function code 

OO(AP) Address of the first function-dependent QIO 


parameter (p1) 


The routine destroys the contents of R2. 


Note that a port driver must set TTY$V_PC_PORTFDT in UCBSW_TT_ 
PRTCTL if it contains a PORT_FDT routine. 


PORT_FORKRET 

The terminal class driver’s service routine, CLASS_FORK, returns control to 
the port driver’s PORT_FORKRET entry point after servicing the port driver’s 
request to create a fork process. (See the description of CLASS_FORK in 
Section 17.5.4.) The only context returned from the servicing of the fork 
request is the address of the UCB in R5. 


The terminal class driver issues a a JMP instruction (rather than a JSB 
instruction) to the PORT_FORKRET routine. 


PORT_MAINT 

The class driver calls the PORT_MAINT routine whenever a $QIO request 
is issued for an IO$_SETMODE function with the IO$M—MAINT modifier. 
The VMS I/O User's Reference Manual: Part I lists all possible maintenance 
functions; each port driver must decide which of these functions it must 
support. 


Input to the PORT_MAINT routine is as follows: 


R5 Address of UCB 
UCB$B_TT_MAINT Parameters to the IO$M_MAINT function 


PORT_SET_LINE : 

The PORT_SET_LINE routine changes terminal line parameters. The 
terminal class driver calls the PORT_SET_LINE routine whenever any 
terminal characteristic in UCB$L_DEVDEPEND or UCB$L_DEVDEPND2 
is changed. It also calls this routine when speed, parity, and the enabling or 
disabling of DMA and automatic flow control are affected. 


The PORT_SET_LINE routine is the only port routine that is allowed to write 
the fields UCB$L_DEVDEPEND and UCB$L_DEVDEPND2. 
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17.4.2.7 


17.4.2.8 
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Input to the PORT_SET_LINE routine is as follows: 


R5 Address. of UCB. 

UCB$B_TT_MAINT Parameters to the IO$M_MAINT function. 
UCB$B_TT_PARITY Parity, stop bits, and frame size. 
UCB$W_TT_SPEED Low byte indicates transmit speed; high byte 


indicates receive speed or is zero. 


UCBSW_TT_PRTCTL DMA enable flag (TTY$V_PC_DMAENA) and auto 
XOFF enable flag (TTY$V_PC_XOFENA) 


UCB$L_DEVDEPEND First longword for device-dependent status. 
UCB$L_DEVDEPND2 Second longword for device-dependent status. 


The PORT_SET_LINE routine destroys the contents of R4. 


PORT_SET_MODEM 

A call to the PORT_SET_MODEM routine informs the port that the line 

has been enabled for modem signal input transitions. A port implementing 
modem functions must ensure that the hardware is ready to detect changes in 
input modem signals. When hardware does not provide this capability (as, for 
instance, the DZ11 terminal controller does not), the VMS terminal class/port 
interface implements the equivalent capability by using timer-based polling. 


At the time of the call, R5 contains the address of the UCB. 


PORT_STARTIO 

The terminal class driver calls the PORT_STARTIO routine to start output on 
a line that is currently inactive. The PORT_STARTIO routine is always called 
with either a character or a burst of data and it is never called unless the line 
is idle (UCB$V_INT is clear in UCB$W_STS). 


The UCB$V_INT bit functions as an interlock, signifying that the port output 
logic is busy. The class driver always sets UCB$V_INT when it calls PORT_ 
STARTIO. If the port requests that timers be set up (TTY$V_PC_NOTIME 

clear in UCBSW_TT_PRTCTL), then the class driver calculates and creates an 
output timer for the burst or character and sets UCB$V_TIM in UCB$L_STS. 


Input to the PORT_STARTIO routine is as follows: 


RO First |/O status longword (IRP$L_IOST 1) 

R3 Character to be output (if UCB$B_TT_OUTYPE is 1) 
R5 Address of UCB 

UCB$B_TT_OUTYPE Zero if there is no character to be output; 1 if there 


is one character to be output; and a negative value if 
there is a burst to be output 


UCB$L_TT_OUTADR Address of burst to output (if UCB$B_TT_OUTYPE is 
negative) 
UCB$W_TT_OUTLEN Length of burst (if UCB$B_TT_OUTYPE is negative) 


Terminal Class and Port Drivers 
17.4 Port Driver Routines 


17.4.3 Port Service Routines 


Note: 


17.4.3.1 


17.4.3.2 


17.4.3.3 


17.4.3.4 


The terminal class driver can call port service routines at any time. 


Because they must consist of reentrant code, port service routines cannot 
issue callbacks to the class driver. 


A call to a port service routine uses the following instruction format: 


MOVL UCB$L_TT_PORT(RS5),RO ;get pointer to port vector table 
JSB @PORT_ABORT (RO) ;call port abort routine 


Note that a port service routine must preserve the contents of all registers. 
PORT_ABORT 

The terminal class driver calls the PORT_ABORT routine to abort any 
currently active output activity: for instance, the last burst of output sent 


to the port. The PORT_ABORT routine invalidates the contents of the 
address stored in UCB$L_TT_OUTADR. 


At-the time of the call, R5 contains the address of the UCB. 


PORT_CANCEL 


The terminal class driver calls the PORT_CANCEL routine in servicing a 


$CANCEL, $DASSGN, or $DALLOC request. The PORT_CANCEL routine 
cancels any internally queued operations for the port. Most commonly, a call 
is issued to this routine when a request to establish an outgoing connection 
has been stalled because the port is busy. 


Input to the PORT_CANCEL routine is as follows: 


R2 Channel index number 

R4 Address of current PCB 

R5 Address of UCB 

R8 Reason for cancellation, one of the following: 
CAN$C_CANCEL Called by $CANCEL system service 
CAN$C_DASSGN Called by $DASSGN or $DALLOC system service 


PORT_RESUME 

The terminal class driver calls the PORT_RESUME routine to resume any 
previously stopped output. The port must be prepared for this routine to be 
called at any time (whether output is currently active or has previously been 
stopped). The PORT_RESUME routine should always ensure that the port 
hardware is enabled for output. 


At the time of the call, R5 contains the address of the UCB. 

PORT_STOP 

The PORT_STOP routine halts the output data stream. The terminal class 
driver normally calls this routine in response to input flow control. When 


called, the PORT_STOP routine should stop the data stream as soon as 
possible. 


At the time of the call, R5 contains the address of the UCB. 
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17.4.3.5 


17.4.3.6 


17.4.3.7 


PORT_XOFF 

The terminal class driver calls the PORT_XOFF routine when it is 
approaching or has reached its input limit. The PORT_XOFF routine takes 
steps to stop the input data stream. For character-oriented controllers, it 
commands the port to insert the flow control character in the output data 
stream as soon as possible. 


Input to the PORT_XOFF routine is as follows: 


R3 Flow control character to be inserted in the input data 
stream 

R5 Address of UCB 

UCB$L_STS UCB$V_INT may or may not be set 


The PORT_XOFF routine must set UCB$V_INT in UCB$L_STS. 


PORT_XON 

The terminal class driver calls the PORT_XON routine when it has cleared its 
input path and is ready to accept data. For character-oriented controllers, the 
PORT_XON routine commands the port to insert the flow control character in 
the input data stream. 


Input to the PORT_XON routine is as follows: 


R3 Flow control character to be inserted in the input data 
stream 

R5 Address of UCB 

UCB$L_STS UCB$V_INT may or may not be set 


The PORT_XON routine must set UCB$V_INT in UCB$L_STS. 


Port Interrupt Service Routines 

A terminal port driver must contain code to service receiver interrupts and 
transmitter interrupts. The exact form of a device interrupt associated with 
the port driver is device dependent. For multiple-line interfaces, the port 
driver must also determine which line is requesting the interrupt and move its 
UCB address into R5. 


To service receiver interrupts, the port driver obtains a character from the port, 
together with hardware error flags that signal a parity, overrun, or frame error 
in the transaction. It proceeds as follows: 


e If an error has been detected, the port driver passes the character and 
error flags to the CLASS_READERROR service routine for processing (for 
instance, autobaud detection). 


e If no error has been detected, the port driver passes the character to the 
CLASS_PUTNXT service routine. 


If either of these service routines returns characters that must be echoed 
and the line is currently inactive, the port driver must start output. Before 
dismissing the interrupt, the port driver for a controller with multiple lines 
should check all lines for pending transactions and empty the silo. 
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To service transmitter interrupts, the port driver first records any reported 
errors. It then proceeds as follows: 


e If TTY$V_TP_ABORT is set in UCB$B_TP_STAT, the port driver calls the 
PORT_ABORT service routine to terminate the transaction. 


e¢ If TTY$V_TP_ABORT is not set, the port driver sets up the next output 
sequence according to the following priority: 


Transaction Use 

Preempt Normally used to send an XON or XOFF character 
Hold Normally used for single-character output 

Burst Used for multiple-character (DMA) output 


Note that this action can result in an XON or XOFF character appearing 
in the middle of an escape sequence. 





17.5 Class Driver Routines 


Table 17-2 lists the class driver routines that are part of the class /port 
interface. This section describes the functions and context of each listed 
routine. 


A call to a class service routine uses the following instruction format: 
MOVL UCB$L_TT_CLASS(R5),RO ;get pointer to class vector table 
JSB @CLASS_DISCONNECT(RO) ;call class disconnect routine 


Table 17—2 Class Driver Routines 


Routine Function 

CLASS_DDT Pointer to the driver dispatch table 

CLASS_DISCONNECT Disconnects a process from a terminal on a 
nonmodem line 

CLASS_DS_TRANS Manages data set transitions 

CLASS_FORK Services a port driver’s request to create a fork 
process 

CLASS_GETNXT Delivers to the port driver the next character or 
burst to be output 

CLASS_PUTNXT Obtains input characters from the port driver 

CLASS_SETUP_UCB Initializes the UCB 

CLASS_POWERFAIL Services a power failure 

CLASS_READERROR . Services a parity, data overrun, or framing error on 


a terminal line 
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17.5.1 CLASS_DDT 


This entry in the class driver vector table points to the driver dispatch table 
(DDT). The CLASS_UNIT_INIT macro uses the CLASS_DDT entry point 
when moving the address of the DDT into the UCB. 


17.5.2 CLASS_DISCONNECT 


A port driver calls the CLASS_DISCONNECT routine to indicate to the 
terminal class driver that the terminal is no longer connected to the system. 
This is the preferred way of disconnecting a process from a terminal on a 
nonmodem line. 


At the time of the call, R5 must contain the address of the UCB. The CLASS_ 
DISCONNECT routine destroys the contents of R4. 


17.5.3 CLASS_DS_TRANS 


17.5.4 CLASS_FORK 
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This CLASS_DS_TRANS routine manages data set state transitions. The 
port driver’s unit initialization routine must call this routine with the 
transition type MODEM$C_INIT in R1 if the unit is capable of having 
data set transitions. (Note that, to use modem symbols, the port driver 
must invoke the $TTYMDMDEF data structure definition macro (from 
SYS$LIBRARY:LIB.MLB). 


Input to the CLASS_DS_TRANS routine is as follows: 


R1 Transition type, one of the following: 


MODEMS$C_INIT Initialize modem control 

MODEM$C_INIT_NORESET Start modem protocol, but do 
not initialize signals 

MODEM$C_SHUTDWN Shut down the line and 


disconnect the process 
MODEM$C_SHUTDWN_NOHANGUP Stop modem protocol but do 
not stop the signals 
MODEM$C_DATASET Data set signal changes 
R2 New receive modem mask (if MODEM$C_DATASET is specified in R1) 
R5 Address of UCB 


The CLASS_DS_TRANS routine destroys the contents of RO through R4. 


A port driver calls the CLASS_FORK routine to create a driver fork process 
that uses the UCB fork block. The port driver must never initiate a fork 
directly—it must always call this routine. 


The CLASS_FORK routine sets up the fork block in the UCB and performs 
the other tasks necessary to store context in the fork block, insert it in a 
processor-specific fork queue, and suspend driver processing. When the fork 
has taken place, the class driver calls the port driver at its PORT_FORKRET 
entry point. 
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At the time of the call, R5 must contain the address of the UCB. The CLASS_ 
FORK routine destroys the contents of R4. 


17.5.5 CLASS_GETNXT 


The port driver calls the CLASS_GETNXT routine whenever it has completed 
the current character or burst to obtain the next characters to be output on 
the unit. If CLASS_GETNXT returns data to the port driver, a timer is set up 
(unless explicitly disabled) and the interrupt expected bit is set. 


At the time of the call, R5 must contain the address of the UCB. Output from 
the CLASS_GETNXT routine includes the following: 


R1 Destroyed 
R2 Number of characters (if R3 contains an address) 
R3 Character to be output (if UCB$B_TT_OUTYPE is 


positive); address of characters to be output (if 
UCB$B_TT_OUTYPE is negative); or no character (if 
UCB$B_TT_OUTYPE is zero) 


R4 | Destroyed 

R5 Address of UCB 

R6 through R11 Destroyed 

UCB$B_TT_OUTYPE Zero if there is no character to be output; 1 if there 


is one character to be output; and a negative value if 
there is a burst to be output 


UCB$L_TT_OUTADR Address of burst to output (if UCB$B_TT_OUTYPE is 
negative) 
UCB$W_TT_OUTLEN Length of burst (if UCB$B_TT_OUTYPE is negative) 


17.5.6 CLASS_PUTNXT 


The port driver calls the CLASS_PUTNXT routine to pass input characters 

to the terminal class driver. The CLASS_PUTNXT routine filters characters 
received from nonpassall units for immediate control sequences. If a slave 
mode unit (that is, generating no unsolicited input) does not have a read 
outstanding, the CLASS_PUTNXT routine ignores the input characters, after — 
performing the control-character filtering. 


If the input characters are to be echoed to the terminal, CLASS_PUTNXT 
calls CLASS_GETNXT to notify the port driver. 


The CLASS_PUTNXT routine may or may not return output data to the port 
driver, depending upon the setting of the interrupt-expected bit (UCB$V_INT) 
in UCB$L_STS. If this bit is set, CLASS_PUTNXT does not return data. If it 
does return data, the terminal port driver should assume that more data may 
follow, and call CLASS_GETNXT after outputting the returned data. 


Input to the CLASS_PUTNXT routine is as follows: 


R3 Input character 
R5 Address of UCB 
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Output from the CLASS_PUTNXT routine is as follows: 


R1 
R2 
R3 


R4 

R5 

R6 through R11 
UCB$B_TT_OUTYPE 
UCB$L_TT_OUTADR 


UCB$W_TT_OUTLEN 


17.5.7 CLASS_SETUP_UCB 


Destroyed 

Number of characters (if R3 contains an address) 
Character to be output (if UCB$B_TT_OUTYPE is 
positive); address of characters to be output (if 
UCB$B_TT_OUTYPE is negative); or no character (if 
UCB$B_TT_OUTYPE is zero) 

Destroyed 

Address of UCB 

Destroyed 

Zero if there is no character to be output; one if there 


is one character to be output; and a negative value if 
there is a burst to be output 


Address of burst to output (if UCB$B_TT_OUTYPE is 
negative) 
Length of burst (if UCB$B_TT_OUTYPE is negative) 


A port driver’s unit initialization routine calls CLASS_SETUP_UCB when it 
is invoked at system startup and power failure. 


The CLASS_SETUP_UCB routine initializes the unit’s fork block; write queue 
(UCB$L_TT_WFLINK); break, passall, and DMA device characteristics; and 
read timed out dispatch field (UCB$L_TT_RTIMOUV). 


In addition, it initializes several UCB fields as follows: 


UCB$L_TT_LOGUCB 
UCB$L_DEVCHAR 
UCB$L_DEVCHAR2 
UCB$W_TT_CURSOR 
UCB$W_TT_HOLD 
UCB$W_TT_SPEED 
UCB$B_TT_PARITY 
UCB$B_DEVTYPE 


Address of UCB 
DEV$V_AVL set 
DEV$V_RED cleared 
1 

Cleared 
UCB$W_TT_DESPEE 
UCB$B_TT_DEPARI 
UCB$B_TT_DETYPE 


At the time of the call, R5 must contain the address of the UCB. 


17.5.8 CLASS_POWERFAIL 


A port driver’s unit initialization routine calls the CLASS_POWERFAIL 
routine when it detects a power failure. 


At the time of the call, R5 must contain the address of the UCB. 
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Output from the CLASS_POWERFAIL routine includes the following: 


UCB$W_STS UCB$V_INT cleared; UCB$V_TIM set 
UCB$L_DUETIM Cleared 


17.5.9 CLASS_READERROR 


A port driver calls CLASS_READERROR when it detects a parity, data 
overrun, or framing error on the terminal line. CLASS_READERROR 
completes the read operation with error status if a read is active, or simply 
returns if no read is active. 


Input to the CLASS_READERROR routine is as follows: 


R3 Character and flags. The following flags are defined: 


Bit 12 Parity error on the given character 
Bit 13 Framing error on the given character 
Bit 14 Data overrun 


R5 Address of UCB. 


Output from the CLASS_READERROR routine is as follows: 


RO through R3 Destroyed 


UCB$B_TT_OUTYPE Zero if there is no character to be output; 1 if there 
is one character to be output; and a negative value if 
, there is a burst to be output 
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18 Mapping to I/O Space and the Connect-to-Interrupt 
Facility 


Programs written in VAX MACRO can interface with the I/O subsystem by 
using VMS RMS, by using the Queue I/O Request ($QIO) system service, 
or by mapping to I/O address space and connecting to a device interrupt | 
vector. Programs written in a high-level language can interface with the 1/O 
subsystem using the same methods as a VAX MACRO program, or they can 
-issue the I/O statements specific to that language. In the latter case, the 
program interfaces with the I/O subsystem by means of the VAX Common 
Run-Time Procedure Library. 


A user program can interface with the I/O subsystem at one of several levels, 
depending on its requirements. At each level, the user program makes trade- 
offs between ease of use and execution speed. As a general rule, the closer 
to the VMS executive that a user program interfaces, the less overhead is 
involved in the I/O operation. The connect-to-interrupt capability offers the 
least overhead. 


A process with suitable privileges can connect to a device interrupt vector 
or map the system’s I/O address space into process virtual address space or 
both. Connecting to a device interrupt vector allows your process to respond 
to interrupts from the device with minimal overhead. Mapping system I/O 
address space allows your process to access device registers from the main 
program or from an AST procedure. _ 


A process normally uses these features for devices that do not have VMS 

drivers. These devices must not be direct memory access (DMA) devices, and 

they must be attached to the UNIBUS or Q22 bus. Examples of such devices 
- are the AXV11-C and the KW11-P. 





18.1 1/O Address Space 


In a VAX system, I/O address space is assigned physical address locations of 
200000001¢ and higher (F20000;, and higher for VAX-11/730 and 
VAX-11/780 systems). I/O address space contains device registers that a 
driver or user process can read and write to control a device. Each device 
controller has an associated control and status register (CSR) in I/O address 
space. Device registers for each device are located at an offset from the 
device’s CSR. 


Macros of the format $1OxxxDEF (where xxx represents a specific VAX 
system), contained in SYS$LIBRARY:LIB.MLB, define symbols describing 
the layout of I/O address space. Table 18-1 describes these macros and the 
symbols they define for each VAX system. 
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Table 18—1 Symbols Defined by the $lOxxxDEF Macros 


Macro Symbol(s) Meaning Value (Hex) 

VAX 6200 Series 

$IO9CCDEF lIO9CC$AL_IOBASE Start of |/O address space 20000000 
lO9CC$C_BIWINDOW Offset to node O window space 400000 
lIO9CC$C_BIWSIZ Size of window space 40000 
lIO9CC$C_PERXBI Size of adapter address space 2000000 

VAX 8530/8550/8700/8800/8830/8840 

$IO8NNDEF IOSNN$SAL __NBIB_O Start of |/O address space for VAXBI O 20000000 
IO8NN$AL _—_NBIB_ 1 Start of |/O address space for VAXBI 1 22000000 
IOSNN$SAL_NBIB_2 Start of 1/O address space for VAXBI 2 24000000 
IO8NN$AL __NBIB_3 Start of 1/O address space for VAXBI 3 26000000 
lIOSNN$AL _NBIB_4 Start of |/O address space for VAXBI 4 28000000 
IOSNNSAL_NBIB_5 Start of 1/O address space for VAXBI 5 2A000000 
IO8NN$AL_NODESP Offset to node 0 window space 400000 
lIO8NN$AL_NDSPER Size of window space 40000 

VAX 8200/8250/8300/8350 

$IO8SSDEF l1O8SS$AL_NODESP Address of node 0 window space 20400000 
lIO8SS$AL_NDSPER Size of window space 40000 

VAX 8600/8650/8670 

$10790DEF lO790$AL _IOAO Start of |/O address space for SBIO 20000000 
lIO790$AL_IOA1 Start of 1/O address space for SBI1 22000000 
1O790$AL__UBOSP Offset to start of adapter address space 24000000 

for first UNIBUS 

VAX-11/780 and VAX-11/785 

$10780DEF lO780$AL_IOBASE Start of |/O address space 20000000 
lIO780$AL __UBOSP Start of adapter address space for first UNIBUS 20100000 

VAX-11/750 

$10750DEF' lIO750$AL_IOBASE Start of |/O address space F20000 
lIO750$AL__UBBASE Start of UBAO adapter register space F30000 
10750$AL_MBBASE Start of MBAO adapter register space F28000 
10750$AL_UBOSP Start of adapter address space for first UNIBUS FCOOOO 

VAX-11/730 and VAX-11/725 

$10730DEF 1IO730$AL_IOBASE Start of |/O address space F20000 
1IO730$AL __UBOSP Start of adapter address space for UNIBUS FCOOOO 





'The VAX-—11/750 system has fixed MASSBUS adapters (UBBASE, MBBASE) in contrast to the VAX—11/780 system, 
which has floating MASSBUS adapters, and the VAX—11/730, which does not have MASSBUS adapters. 
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Table 18—1 (Cont.) Symbols Defined by the $10xxxDEF Macros 
Macro Symbol(s) Meaning 


MicroVAX 3600 Series 


$IO650DEF 1O650$ AL __OBOSP Start of adapter address space for O22 bus 
MicroVAX Il 
$lIOUV2DEF IOUV2$AL_—QBOSP Start of adapter address space for Q22 bus 
MicroVAX | 
$lIOUV 1DEF lIOUV 1$AL__QBOSP Start of adapter address space for 022 bus 


Value (Hex) 


20000000 


20000000 


20000000 


The number of registers and their locations varies from device to device. 
The PDP-11 Peripherals Handbook provides the necessary information 
for DIGITAL-supplied devices. The VAX Hardware Handbook contains 


information about the layout of I/O address space. 


From the symbols defined by the macros described in Table 18-1, you can 
derive the starting physical addresses of UNIBUS or Q22 bus adapter address 
space for the various VAX systems. Table 18-2 lists the starting physical 
addresses for UNIBUS adapters on the VAX 8600/8650/8670, VAX-11/780, 
VAX-11/785, VAX-11/750, VAX-11/730, and VAX-11/725 systems, as 
well as the starting physical addresses for MicroVAX I, MicroVAX II, and 


MicroVAX 3600-series Q22 bus interface address space. 


Note: To access UNIBUS device CSRs you must add 3E000;, to the addresses 
listed in Table 18-2. This operation is not necessary when you use the 


values supplied for MicroVAX/Q22 bus systems. 


For VAX 8530/8550/8700/8800 and VAX 8200/8250/8300/8350 systems, 
Example 18-1 illustrates the calculations that are necessary to determine the 
location of the adapter address space for a given DWBUA adapter on a VAXBI 
bus. For additional information on the layout of VAXBI I/O address space, 


see the discussion and illustrations in Section 14.2. 


Table 18-2 UNIBUS and Q22 Bus Adapter Address Space 


VAX-11 MicroVAX 
UNIBUS /780 3600 Series VAX 8600 SBIO/SBI1 
Adapter VAX-11/725 VAX-11 MicroVAX II VAX 8650 SBIO/SBI1 
Number VAX-11/730 VAX-11/750 = /785 MicroVAX | VAX 8670 SBIO/SBI1 
0 OOFCOO0O OOFCO00O 20100000 20000000 20100000/22 100000 
1 : 0OF80000 20140000 - 20140000/22 140000 
2 Z s 20180000 - 20180000/22 180000 
3 “ = 201C0000.—s - 201C0000/221C0000 
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Example 18—1_ Locating the Adapter Address Space of a DWBUA Adapter on a VAXBI Bus 





For VAX 8530/8550/8700/8800: 


IO8NN$AL_NBIB_n ;Start of I/0 address space for given VAXBI bus 
+ IO8NN$AL_NODESP ;Offset to window space 
+ IO8NN$AL_NDSPER + VAXBI-node-ID-of-DWBUA ;Offset to given VAXBI node window space 
+ UNIBUS-address-of-device-CSR ;Offset to device CSR 
For VAX 8200/8250/8300/8350: 
IO8SS$AL_NODESP ;Start of window space 
+ IO8SS$AL_NDSPER * VAXBI-node-ID-of-DWBUA ;Offset to given VAXBI node window space 
+ UNIBUS-address-of-device-CSR ;Offset to device CSR 


For most VAX processors, the page frame number (PFN) of a physical page 

in memory is contained in bits 9 through 29 of its physical address (see 
Figure 18-1). Bit 29 of the address is clear to indicate a physical memory 
address and set to indicate an address in I/O address apa Bits 0 through 8 
specify the byte address within the page. 


Figure 18—1 Format of a Physical Address 


31 30 29 


2K-4845-85 
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PFN Mapping 


For a process to gain access from an outer access mode to I/O address space 
or to any page of physical memory, it must map that page into its virtual 
address space. When a VMS process maps a page by specifying its page 
frame number, it completely bypasses VMS memory management and creates 
its own window to the page. As a result, the protection functions that VMS 
normally performs are not performed for PFN mapping: 


e No checks are performed to ensure that no other VMS processes are 
mapped to the page and modifying it. 


e No reference count is maintained. A process can delete a global section 
mapped by page frame numbers when other processes are still using it; 
this is not the case for other types of global sections. 


Modifying pages mapped by page frame numbers can have unpredictable 
results and can adversely affect system operation, especially if the operating 
system is also using these pages or accessing devices whose registers are in 
the same pages. Because PFN-mapped pages are not inherently protected 
from such modification, a process must have the PFNMAP privilege to use 
this capability. 


When used for PFN mapping, the Create and Map Section (§$CRMPSC) 
system service designates the specified page(s) as a global or private section 
and maps the section into the requesting process’s virtual address space. The 
pages can be located anywhere in the VAX system’s local memory, in MA780 
memory (if a multiport memory unit is connected to the system), or in I/O 
address space. 


The format and conventions for PFN mapping (that is, mapping a physical 
page frame section) are similar to those for mapping a disk file section. The 
$CRMPSC system service has the following general formats: 


VAX MACRO Format 


$CRMPSC _[inadr] Lretadr] [,acmode] [,flags] [,gsdnam] [,ident] - 
[,relpag] [,chan] [,pagent] [,vbn] [,prot] [,pfc] 


High-Level Language Format 


SYSSCRMPSC ({inadr] [,retadr] [,acmmode] [,flags] [,gsdnam] [,ident] 
[,relpag] [,chan] [,pagcent] [,vbn] [,prot] [,pfc]) 


The relpag, chan, and pfc arguments are not applicable to mapping by 
page frame number. The inadr, retadr, acmode, gsdnam, ident, and prot 
arguments have the same functions regardless of whether you specify page 
frame number mapping. The VMS System Services Reference Manual further 
describes these arguments. | 


The following arguments can have values specific to PFN mapping: 


Arguments 


[flags] 

Mask defining the section type and characteristics. This mask is the logical 
OR of the flag bits you want to set. The $5ECDEF macro defines symbolic 
names for the flag bits in the mask. The SEC6M_PFNMAP flag bit must be 
set to indicate mapping by page frame number. The SEC$M_PFNMAP flag 
setting identifies the memory for the section as starting at the page frame 
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number specified in the vbn argument and extending for the number of pages 
specified in the pagent argument. 


If appropriate, the following flags can also be set: 


Flag Description 
SEC$M_GBL Pages form a global section. The default is private section. 


SEC$M_EXPREG Pages are mapped into the first available space. By default, 
pages are mapped into the range specified by the inadr 
argument. 

SEC$M_WRT Pages form a read/write section. By default, pages form a 
read-only section. 


SEC$M_PERM Pages are permanent. By default, pages are temporary. 


SEC$M_SYSGBL Pages form a system global section. By default, pages 
. form a group global section. 


You must not set either the SEC6M_CRF (copy-on-reference) or the SEC6M_ 
DZRO (demand-zero) bit when mapping by page frame number. 


[pagent] 
Number of pages in the section; the value of this argument must not be zero. 


[vbn] 

Page frame number of the first page to be mapped (as opposed to this 
argument’s normal usage identifying the starting virtual block number (vbn) 
within a disk file). When you are mapping more than one page with a single 
$CRMPSC system service request, the pages are physically contiguous starting 
with the specified page. 


18.2.1 Notes on PFN Mapping 


The following considerations apply to PFN mapping. 


1 An error in mapping UNIBUS or Q22 bus adapter address space or a 
reference to a nonexistent bus address causes a UNIBUS adapter error. 
However, this error does not cause a system failure (except on a VAX 
8530 /8550/8700/8800/8830/8840, VAX-11/750, or VAX-11/730 
system, where a machine check will occur). Rather, an entry is made 
in the system error log file and the user program continues executing 
(probably with erroneous results). The process is not notified of the 
UNIBUS adapter error. 


2 On systems where a UNIBUS power failure can occur without causing a 
system failure, a user process receives a machine check exception, if it is 
using perprocess space mapping when accessing UNIBUS or Q22 bus I/O 
address space during the failure. To survive this exception, the process 
must have a condition handler to deal with machine check exceptions. 
The VMS System Services Reference Manual discusses condition handlers in 
detail. 


3 During recovery from a power failure, the processor spends a considerable 
amount of time (perhaps 10 to 60 milliseconds) at IPL 31. This action 
blocks user processes from executing during the recovery. 
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4 When a process requests deletion of a PFN-mapped page, VMS will wait 
until there is no direct I/O outstanding for the process before deleting the 
page. This is because no reference count is maintained for PFN-mapped 
pages. (For example, VMS cannot determine whether outstanding direct 
I/O is for the PFN-mapped page or not.) Applications using devices that 
have direct I/O perpetually outstanding, such as the DR32, must not 
delete PFN-mapped pages because this will cause the process to hang in 
the MWAIT state. 


Once you have mapped to I/O address space, you can read data from a 
device data buffer register, because the device registers are now addressable 
as part of your process’s virtual memory. The UNIBUS adapter performs the 
actual mapping of VAX virtual addresses to the 18-bit UNIBUS addresses 
that correspond to device registers. Likewise, the MicroVAX 3600-series, 
MicroVAX II, or MicroVAX I system performs the mapping of virtual 
addresses to 22-bit Q22 bus addresses that correspond to device registers. 


See Section 5.2 for a list of restrictions that apply to instruction references to 
device register address space. 





Connecting to an Interrupt Vector 


You can use the $QIO system service with an appropriate function code to 
connect to a device interrupt vector and to specify.a user-supplied interrupt 
service routine that VMS executes when the designated device interrupts. 
Connecting to a device interrupt vector allows you to do the following: 


¢ Respond to an interrupt within a short time 


e Preempt other system processing to handle a real-time event, for example, 
a clock interrupt 


e Buffer data from a device in real time and return the data to the process 
at a later time 


e Set an event flag or queue an AST to your process after receiving the 
interrupt 


An interrupt service routine specified in your process allows it to perform 
some of the functions normally performed by a device driver. The connect- 
to-interrupt facility, with its VMS-supplied driver (CONINTERR), thus allows 
you to avoid writing a full device driver and loading it into the operating 
system. 


If you must access device registers from user mode (that is, from the main 
program or a user-mode AST procedure), you must use the Create and Map 
Section (6CRMPSC) system service to map I/O address space, specifying page 
frame number (PFN) mapping. The service creates a global or private section 
that maps the specified I/O pages into your process’s virtual address space 
with suitable protection. The process can then gain access to I/O address 
space using perprocess virtual addresses (see Section 18.1 for additional 
discussion). 


You do not need to map I/O address space to access device registers from 
any of the following routines specified in the $QIO call connecting to an 
interrupt vector: 


e Unit initialization routine 
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e Start-I/O routine 


e Interrupt service routine 


* Cancel-I/O routine 


These routines execute in system context and thus can access UNIBUS or Q22 
bus I/O address space, which is mapped as part of system address space. 


18.3.1 Performing the Connect-to-Interrupt 


18-8 


Connecting to a device interrupt vector allows your program to receive 
notification of an interrupt from a designated device by any combination of 
the following means: 


¢ By execution of a user-supplied interrupt service routine 
e By the setting of an event flag 


e By execution of an AST procedure that gains control in process context 


In addition, you can specify a cancel-I/O routine that is executed when the 
process disconnects from the interrupt vector or is deleted. 


Before your program can run, the system manager must have performed the 
following actions at system generation time: 


e¢ Specify the REALTIME_SPTS system parameter, reserving system page 
table entries for use by real-time processes. These system page-table 
entries are used to map process-specified buffers in system address space 
(see the p1 argument description in Section 18.3.2). The REALTIME_SPTS 
parameter value must be greater than or equal to the number of pages in 
buffers specified by processes connected to interrupt vectors. 


¢ Configure the real-time device by issuing a CONNECT command to the 
System Generation Utility. This command names the device; its vector, 
register, and adapter addresses; and a skeletal driver (CONINTERR) 
for the device. (See the description of the CONNECT command in 
Section 15.2.2 and in the VMS System Generation Utility Manual.) 


At run time the process calls the $ASSIGN system service to associate a 
channel with the device. To connect to the device interrupt vector, the 
process issues a $QIO call specifying the IO$_.CONINTREAD or IO$_ 
CONINTWRITE function code and as many of the following items as are 
appropriate: 


e An interrupt service routine to be executed when the device generates an 
interrupt. 


e A unit initialization routine. 
e 6A start-I/O routine. 
¢ Acancel-I/O routine. 


e¢ A buffer containing the code to be executed in system context, data (that 
is, the previously-listed routines), or both. 
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e An AST procedure to execute, an event flag to be set after the interrupt 
service routine (if any) completes, or both. (If an AST procedure is 
specified, an AST parameter may also be specified.) 


A nonprivileged process (that is, lacking the CMKRNL privilege) can also 
connect to an interrupt vector, but it can only specify an AST procedure to be 
executed or an event flag to be set (or both) when an interrupt is generated. 
The process can also map the page in UNIBUS or Q22 bus I/O address space 
containing the device registers (see Section 18.2). 


18.3.2 $Ql10 Connect-to-Interrupt Request to Driver 


The format of the $QIO system service to connect to an interrupt vector 
follows. This explanation is limited to connecting to an interrupt vector. For 
a detailed description of the $QIO system service, see the VMS System Services 
Reference Manual. 


VAX MACRO Format 


$QlO_ [efn] ,[chan] ,func [,iosb] [,astadr] [,astprm] - 
[p1] [.p2] [.p3] L.p4] Lp5] [.p6] 


High-Level Language Format 


SYS$QIO ([efn] ,[chan] ,func [,iosb] [,astadr] [,astprm] 
[p1] Lp2] [.p3] [.p4] Lp5) [.p6)) 


Arguments 


[efn] 

[chan] 

[iosb] 

[astadr] 

[astprm] 
These arguments apply to the $QIO system service completion, not to device 
interrupt actions. For an explanation of these arguments, see the description 
of the $QIO system service in the VMS System Services Reference Manual. 


func 

Function code of IO$_CONINTREAD or IO$_CONINTWRITE. The IO$_ 
CONINTWRITE function code allows locations in the buffer pointed to by the 
pl argument to be modified; the IO$__CONINTREAD function code makes 
the buffer contents read-only. 


[p1] 

Address of a descriptor for the buffer containing code and/or data. The first 
longword records the number of bytes in the buffer; the second longword 
records the address of the buffer. The buffer size must not exceed 65,535 
bytes. 


[p2] 
Address of an entry point list. The list consists of four longwords that contain 
offsets into the buffer (specified in the p1 argument) of the entry points 
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of process-specified routines. These longwords and their contents! are as 


follows: 

Symbol Meaning 

CINSL_INIDEV Offset to unit initialization routine 
CINSL_ST ART Offset to start-I/O routine 
CINSL_ISR Offset to interrupt service routine 


CINS$L__CANCEL Offset to cancel-1/O routine 


[p3] 


Longword containing flags and an optional event flag number specification. 


The low-order word contains the inclusive-OR of flags describing options to 
the connect-to-interrupt facility. The flags and their meanings are as follows: 


Flag Meaning 


CINSM_EFN Set event flag on interrupt. 


CINSM_USECAL Use CALL interface to process-specified routines (default is 
JSB interface). 


CINSM_REPEAT Leave process connected to the interrupt vector until the 
connection is canceled. 


CINSM_INIDEV Process-specified unit initialization routine is in the buffer 
specified in the p1 argument. 

CINSM_START Process-specified start-|/O routine is in buffer. 

CINSM_ISR Process-specified interrupt service routine is in buffer. 


CIN$M_CANCEL Process-specified cancel-l/O routine is in buffer. 
The high-order word specifies the number of the event flag to-be set when an 
interrupt occurs. This number is expressed as an offset to CIN$V_EFNUM. 


For example, to specify that your interrupt service routine is in the buffer and 
to set event flag 4, code p3 as follows: 


P3 = <CIN$M_ISR!CIN$M_EFN! 4@CIN$V_EFNUM> 
See note 3 in the following description for additional information on these 


flags. 


[p4] 7 
Address of the entry mask of an AST procedure to be called as the result of 
an interrupt (see Section 18.3.5). 


[p5] 

AST parameter to be passed to the AST procedure (used as the AST 
parameter only if the process-supplied interrupt service routine does not 
overwrite the value). 


" The listed symbols are. defined by the $CINDEF macro located in the library SYS$LIBRARY:LIB.MLB. 
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Number of AST control blocks to preallocate in anticipation of fast, recurrent 
interrupts from the device. 


Condition Values Returned 


SS$_NORMAL 
SS$_ACCVIO 


SS$_BADPARAM 


SS$_DISCONNECT 


SS$_EXQUOTA 


SS$_ILLEFC 
SS$_INSFMEM 


SS$_INSFSPTS 


SS$_NOPRIV | 


SS$_UNASEFC 


System service successfully completed. 


The caller does not have the appropriate access to the 
buffer specified in the p1 argument or to the entry point 
list specified in the p2 argument. 


The size of the buffer specified in the p1 argument 
exceeds 65,535 bytes, or the number of preallocated 
AST control blocks specified in the P6 argument exceeds 
65,535. 


A connection is already outstanding for the device, or a 
condition described as follows in note 2b has occurred. 


The process has exceeded its direct I/O limit quota or its 
AST limit quota. 


An illegal event flag number was specified. 


Insufficient system dynamic memory is available to 
complete the system service. 


Insufficient system page-table entries are available 
to double map the process buffer. (The value of the 
REALTIME_SPTS SYSGEN parameter must be increased.) 


The process does not have the CMKRNL privilege. This 
privilege is only required if the user specifies a buffer — 
to be used by the process and the process-specified 
kernel-mode routines. 


The process is not associated with the cluster containing 
the specified event flag. 


Privilege Restrictions 


The connect-to-interrupt $QIO call does not require privileges if no shared 
buffer is specified. If the request specifies a buffer descriptor argument (that 
is, p1), the process must have the CMKRNL privilege. 


Resources Required/Returned 


A connect-to-interrupt request updates the process quota values as follows: 


e Subtracts the number of preallocated AST control blocks in the p6 
argument from the number of outstanding ASTs remaining for the 


process (ASTCNT) 


e¢ Subtracts 1 (for the $QIO) from the direct I/O count (DIOCNT) 
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Notes 

1 After the $QIO call is issued, the operation is not completed until the 
process or the connect-to-interrupt driver cancels I/O on the channel. 

2 The connect-to-interrupt driver can cancel I/O on the channel for a 
number of reasons, including the following: 

a. The driver cannot set the specified event flag, perhaps because 
the process disassociated from the common event flag cluster after 
requesting that a flag in that cluster be set. 

b. The driver cannot reallocate AST control blocks quickly enough. 
This condition can occur because not enough AST control blocks 
(p6 argument) were specified, not enough pool space is available for 
the requested AST control blocks, or the process ASTCNT quota is 
exhausted. 

c. The driver cannot queue the AST to the process. 

3 If no event flag setting was requested in the p3 argument and if no 


AST procedure was specified in the p4 argument, p6 is ignored and no 
AST control blocks are preallocated. If you requested that an event flag 
be set or specified an AST procedure, but did not preallocate any AST 
control blocks (that is, p6 is zero), one AST control block is preallocated 
automatically, because the system needs one control block to set any 
event flag or to deliver any ASTs. 


If you request an event flag and/or an AST procedure and if you 
preallocate any AST control blocks, the CINSM—REPEAT bit is set 
automatically in the longword specified in the p3 argument. Thus, 

as long as you preallocate any AST control blocks, your process will 
automatically remain connected to the interrupt vector to receive repeated 
interrupts until the process is disconnected from the interrupt vector. 


If the CINSM_REPEAT flag is not set, the process is disconnected from 
the interrupt vector after the first successful interrupt, and a status code of 
SS$_NORMAL is returned. 


18.3.3 The Connect-to-Interrupt Driver (CONINTERR. EXE) 


The VMS connect-to-interrupt driver (CONINTERR) provides a driver 
interface to the system on behalf of the process. CONINTERR connects 
the process to the device by executing the following steps: 


18-12 


1 


Validates the arguments to the $QIO system service call, such as the 
accessibility of the buffer specified in argument p1 to the process, and the 
number of the event flag optionally specified in the efn argument. 


Locks the physical pages of the buffer into physical memory, and maps 
the pages using system page-table entries allocated by the REALTIME _ 
SPTS SYSGEN parameter. 


Constructs argument lists and calling interfaces to the process-specified 
routines by storing values in the device’s unit control block (UCB). 


Allocates the specified number of AST control blocks to the process, and 
inserts each block in a queue in the device’s UCB. 
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5 Transfers control to VMS to queue the connect-to-interrupt I/O packet to 
the CONINTERR start-I/O routine. 


When the CONINTERR start-I/O routine gains control, it passes control, by 
means of a user-specified JSB or CALLS instruction interface, to the process- 
specified start-I/O routine. This routine usually initializes the device and may 
also start device activity. 


When the device generates an interrupt, the CONINTERR interrupt service 
routine gains control. This routine transfers control to the process-supplied 
interrupt service routine. 


18.3.4 Process-Specified Routines 


Any routines that the process specifies in the connect-to-interrupt call, with 
the exception of the AST procedure, are double-mapped, once in process 
address space and once in system address space. Each routine executes in 
kernel mode at an appropriate IPL: 


Routine IPL 

Unit initialization routine (after power IPL$_POWER (IPL 31) 
recovery) 

Start-I|/O routine IPL$_QUEUEAST (IPL 6) 
Interrupt service routine Device IPL 

Cancel-I/O routine IPL$_.QUEUEAST (IPL 6) 


The process must have CMKRNL privilege. Each routine must 
e Be position independent 


¢ Follow the rules for accessing I/O address space as described in 
Section 5.2 


e¢ Access only data within the buffer or nonpageable locations in system 
address space 


e Perform any necessary synchronization of access to data in the shared 
buffer 


¢ Save any registers it uses (unless otherwise noted in the remaining 
sections of this chapter) 


e =Exit properly 
¢ Not incur exceptions 
e Not perform lengthy processing 


e¢ Not dispatch to code outside the buffer specified in the p1 argument to 
the $QIO system service call 


Only VAX MACRO or VAX BLISS-32 should be used to code process- 
specified routines in system address space or any references to I/O address 
space. There is no assurance that the code generated by compilers for other 
languages will satisfy all the constraints described in this section. 
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The following constraints apply to process-specified routines in system 
address space (that is, in the buffer specified in the p1 argument to the $QIO 
call that establishes the connection to the interrupt vector): 


e The compiler must generate position-independent code for the routines. 
e The generated code and data must be contiguous in virtual address space. 


e No calls can be made to any procedure outside the buffer. (This 
restriction includes calls to routines in the VAX Run-Time Library.) 


e For any references to I/O address space, the generated code must follow 
the rules for accessing I/O address space discussed in Section 5.2. 


You can find additional help for writing a start-I/O routine, interrupt service 
routine, unit initialization routine, or cancel-I/O routine in Sections 8, 9, 
11.1, and 11.2, respectively. Additionally, you may find useful the several 
program examples of connecting to an interrupt vector with which this 
chapter concludes. 


Unit Initialization Routine . 

During recovery from a power failure, VMS calls the CONINTERR unit 
initialization routine. This routine marks the device as on line in the UCB$L_ 
STS field, stores the UCB address in the IDB$L_OWNER field, and then 
transfers control to the process-specified unit initialization routine. The 
process-specified routine executes in system context at IPL$_POWER 

(IPL 31). 


If the process specified a JSB interface, the process unit initialization routine 
gains control with the following register settings: 


RO Address of UCB 
R4 Address of CSR 
R5 Address of IDB 

R6 Address of DDB 
R8 Address of CRB 


If the process specified a CALL interface, the process unit initialization routine 
gains control with an argument list pointed to by AP: 

OO(AP) Argument count of 5 

O4(AP) Address of CSR 

O08(AP) Address of IDB 

12(AP) Address of DDB 

16(AP) Address of CRB 

20(AP) Address of UCB 


The process-specified unit initialization routine may initialize device registers. 
It must follow these conventions: 


¢ Not lower IPL nor obtain any spin locks 
e Save and restore all registers it uses, other than RO through R3 


e Restore the stack to its original state before exiting 
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e Exit with an RSB instruction (for a JSB interface) or a RET instruction (for 
a CALL interface) 


For additional information on writing a unit initialization routine, se 
Section 11.1. ; 


Start-1/O Routine 

The process-specified start-I/O routine executes in process context in system 
space at IPL$__QUEUEAST (IPL 6), holding the QUEUEAST fork lock in 

a VMS multiprocessing environment. It is entered from the CONINTERR 
start-I/O routine. 


If the process specified a JSB interface, the process start-I/O routine gains 
control with the following register settings: 


R2 Address of counted argument list 
R3 Address of IRP 
R5 Address of UCB 


If the process specified a CALL interface, the process start-I/O routine gains 
control with an argument list pointed to by AP: 

OO(AP) Argument count of 4 

04(AP) System-mapped address of process buffer 

08(AP) Address of IRP 

12(AP) System-mapped address of the device’s CSR 

16(AP) Address of UCB 


The process-specified start-I/O routine may set up device registers. It must 
follow these conventions: 


e Maintain an IPL equal to or higher than IPL6_QUEUEAST (IPL 6), and 
exit at IPL 6. (If it raises IPL, the routine should first save the current 
IPL on the stack for later use in restoring IPL.) In a VMS multiprocessing 
system, the process-specified start-I/O routine must suitably synchronize 
any access of device registers with the process-specified interrupt service 
routine. To do so, each routine must obtain the appropriate device 
lock, using the VMS-supplied macro DEVICELOCK. Before exiting, each 
routine releases ownership of the device lock using the DEVICEUNLOCK 
macro. (See the discussion of these macros in Appendix B.) 


e Save and restore all registers it uses, other than RO through R4. 
e Restore the stack to its original state before exiting. 


e Exit with an RSB instruction (for a JSB interface) or a RET instruction (for 
a CALL interface). 


For additional information on writing a start-I/O routine, see Chapter 8. 
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Interrupt Service Routine 
A process-specified interrupt service routine is entered when an interrupt 
from the device occurs. This routine executes in system context at device IPL. 


If the process specified a JSB interface, the process interrupt service routine 
gains control with the following register settings: 


R2 Address of counted argument list 
R4 Address of IDB 
R5 Address of UCB 


If the process specified a CALL interface, the process interrupt service routine 
gains control with an argument list pointed to by AP: 

OO(AP) Argument count of 5 

04(AP) System-mapped address of process buffer 

08(AP) Address of AST parameter 

12(AP) System-mapped address of the device's CSR 

16(AP) Address of IDB 

20(AP) Address of UCB 


The process-specified interrupt service routine usually performs one or more 
of the following steps: 


1 Copies the contents of device registers into the shared buffer or the AST 
parameter 


2 Writes to a device register to clear the interrupt condition, if such an 
operation is required for the device 


3 Restarts the device, or returns an offset, a byte count, or actual data as an 
AST parameter 


4 Returns an interrupt status to the VMS connect-to-interrupt driver 
(CONINTERR) 


The process-specified interrupt service routine, like those supplied by VMS, 
has the following characteristics: 


e It is mapped in system address space. 
e It executes on the interrupt stack. 


e It executes at the IPL of the device that requested the interrupt. 


The routine must follow these conventions: 


¢ Maintain an IPL equal to or higher than device IPL. (If it raises IPL, 
the routine should first save the current IPL on the stack for later use 
in restoring IPL.) In a VMS multiprocessing system, if the process- 
specified start-I/O routine or cancel-I/O routine accesses device registers 
or UCB fields also accessed by the process-specified interrupt service 
routine, the routines must suitably synchronize. To do so, each routine 
must obtain the appropriate device lock, using the VMS-supplied macro 
DEVICELOCK. Before exiting, each routine releases ownership of the 
device lock using the DEVICEUNLOCK macro. (See the discussion of 
these macros in Appendix B.) 


¢ Save and restore all registers it uses, other than RO through R4. 
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e Restore the stack to its original state before exiting. 


e Set or clear the low bit of RO, as a status value, before exiting. The status 
values are as follows: 


Bit O of RO Meaning 

Clear — Dismiss the interrupt. The process is not notified of the 
interrupt. 

Set Set the event flag if CINSM_EFN bit is set in the p3 


argument to the $QIO system service call, and queue the 
AST if p4 specifies an AST procedure. 


e Return to the CONINTERR interrupt service routine with a RET 
instruction (for a CALL interface) or RSB instruction (for a JSB interface). 


Depending on the interrupt status returned in RO, the CONINTERR 
interrupt service routine queues a fork process to run at a lower IPL (IPL$_ 
QUEUEAST). Then the interrupt service routine exits from the interrupt with 
an REI instruction. When the CONINTERR fork process gains control, it 
queues an AST or posts an event flag to the process (or both). 


For additional information on writing an interrupt service routine, see 
Chapter 9. 


Cancel-!/O Routine 

When the user process issues a cancel-I/O request for a device connected to 
the process, the CONINTERR cancel-I/O routine first checks to determine 
whether the process can indeed cancel I/O for this device. If it can, the 
CONINTERR cancel-I/O routine transfers control to the process-specified 
cancel-I/O routine. This routine executes in system context at IPL 8 (fork 
IPL). 


If the process specified a JSB interface, the process cancel-I/O routine gains 
control with the following register settings: 


R2 Negated value of channel index number 

R3 Address of current IRP 

R4 Address of PCB for process canceling the I/O 
R5 Address of UCB 


If the process specified a CALL interface, the process cancel-I/O routine gains 
control with an argument list pointed to by AP: 

OO(AP) Argument list count of 4 

O4(AP) Negated value of channel index number 

08(AP) Address of current IRP 

12(AP) Address of PCB for process canceling the 1/O 

16(AP) Address of UCB 


The process-specified cancel-I/O routine may clear device registers and set 
the UCB$V_CANCEL bit in UCB$L_STS. It must follow these conventions: 


e Maintain an IPL equal to o1 higher than IPL$_QUEUEAST (IPL 6), and 
exit at IPL 6. (If it raises IPL, the routine should first save the current IPL 
on the stack for later use in restoring IPL.) In a VMS multiprocessing 
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18.3.5 AST Procedure 


system, if the process-specified cancel-I/O routine accesses device 
registers or UCB fields also accessed by the process-specified interrupt 
service routine, the routines must suitably synchronize. To do so, each 
routine must obtain the appropriate device lock, using the VMS-supplied 
macro DEVICELOCK. Before exiting, each routine releases ownership of 
the device lock using the DEVICEUNLOCK macro. (See the discussion of 
these macros in Appendix B.) 


Save and restore all registers it uses, other than RO through R3. 


Place a completion status in RO and R1. VMS places the values in these 
registers in the I/O status block associated with the connect-to-interrupt 


$QI0 call. 
Restore the stack to its original state before exiting. 


Exit with an RSB instruction (for a JSB interface) or a RET instruction (for 
a CALL interface). 


For additional information on writing a cancel-I/O routine, see Section 11.2. 


The AST procedure that you specify in the call to the $QIO system service 
for the connect-to-interrupt operation gains control in process context. This 
routine usually performs one or more of the following steps: 


1 
2 


Reads or writes device registers if the process mapped I/O address space. 


Interprets data. Use caution, however, because any processing done by 
the AST procedure can be interrupted by a device interrupt, which might 
store more data or modify the buffer’s contents. 


Calls the Cancel I/O on Channel ($CANCEL) system service to 
disconnect the process from the interrupt. Once the process is completely 
disconnected, the CONINTERR driver clears all interrupts for the driver. 
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To understand how the connect-to-interrupt facility is useful for programming 
real-time devices, consider devices used in three types of real-time 
applications: 


1 


Asynchronous event reporting without data—devices that generate an 
interrupt as the result of an external event not initiated by a programmed 
request. 


Program-driven data collection—devices that generate an interrupt as 
the result of a programmed request, and make the result of the request 
available as data in a device register at the time of the interrupt. 


Asynchronous event reporting with data—one device triggers another 
device by generating an interrupt that causes a programmed request to be 


sent to the other device, which in turn generates an interrupt. 
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Examples of these three types of real-time applications and models of 
programs to handle the devices follow. 


Note: The configurations described in the examples in this section are not 
officially supported; DIGITAL does not provide device driver, UETP, 
or diagnostic support for certain devices mentioned. (In fact, DIGITAL 
has officially retired the -K series models (AD11-K and AM11-K A/D 
Converter). The examples are provided merely as possible models for 
users who wish to design real-time applications using unsupported 
devices or configurations. 


The files in the SYS$6EXAMPLES directory whose names begin with “LABIO” 
illustrate an application using the connect-to-interrupt technique. Included is 
a program example illustrating data definitions and coding used to connect to 
a device interrupt vector. 


18.4.1 Example 1: KW11—W Watchdog Timer 


This type of device reports asynchronous external events: it generates an 
interrupt as a result of an external event not initiated by a programmed 
request. The only data of interest to be passed to the user process is the 
occurrence of the external event. Such devices include contact and/or solid 
state interrupts, and clocks or counters. The program may need to activate 
clock and counter devices by means of a programmed request, but any 
subsequent interrupts are the result of external events only. 


In this example, a dual-processor system uses two KW11-W watchdog timers 
connected back-to-back to monitor CPU failures. Each processor must arm 
its timer at regular intervals to prevent the timer from operating a relay that 
outputs an alarm signal. The alarm output of each timer is connected to the 
receive input of the other watchdog. If processor A fails and its watchdog 
times out, the alarm output generates an interrupt on processor B by way of 
the second watchdog timer. 


The watchdog control program on each processor simply addresses the timer 
at regular intervals. If the interval passes without the timer being addressed, 
the timer operates an output relay that generates an interrupt to the second 
CPU. For this example, assume that the interval is 5 seconds. (Section 18.4.3 
contains an example that addresses the problem of a much smaller time 
interval.) 


The watchdog control program on processor A executes as follows: 
1 Assigns a channel to the device 


2 Calls the $CRMPSC system service to map to the I/O page in order to 
address the device registers 


3 Issues a connect-to-interrupt $QIO request to connect the program to the 
watchdog timer for processor B; specifies the addresses of an interrupt 
service routine and an AST procedure 


4 Writes a value to a device register to start the timer 


5 Calls the $SETIMR system service to request that an event flag be set 
after a specified interval (for example, 4 seconds) 


6 Calls the $WAITFR system service to wait for the event flag 
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7 When the event flag is set, writes a value to a device register to reset the 
timer 


8 Loops to step 5 


The same control program runs on processor B except that it connects to the 
watchdog timer for processor A. If either processor fails, the watchdog timer 
generates an interrupt on the other processor. 


The standby processor that receives the interrupt gains control in the VMS 
connect-to-interrupt driver (CONINTERR), which calls a process-supplied 
interrupt service routine (defined in step 3) that handles the interrupt as 
follows: 


1 Sets the KW11-W switch relay register to clear the timer interrupt 
condition 


2 Sets a status flag that will cause an AST to be delivered to the control 
program that connected to the interrupt 


3 Returns to CONINTERR 


CONINTERR completes the interrupt handling as follows: 


1 Schedules a fork process at a lower IPL (IPL$_QUEUEAST). This fork 
process, when it gains control, will queue an AST to the user program. 


2 Executes an REI instruction to return from the interrupt. 


The timer control program on the standby processor regains control in an 
AST procedure which responds to the other processor’s failure by switching 
over and assuming control of the other processor’s tasks (or whatever is 
appropriate). : 


18.4.2 Example 2: AD11—K, AM11—K A/D Converter with Multiplexer 
Connected to the UNIBUS 
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This type of device provides program-driven data collection: it generates an 
interrupt as the result of a programmed request to the device, and makes the 
result of the request available as data in a device register. Typical devices 
include A/D converters and digital I/O registers. 


The data collection operation is usually repetitive for such applications. 
Therefore, the interrupt service routine must be capable of buffering data 
from the device in order to ensure that no data is lost because of the high- 
speed data transfer rate. A typical buffer size for this sampling technique 
might be 32 16-bit words. 


In this example, a user program controls an AD11-K/AM11-K combination 
that accepts analog data from thermocouples. The AD11-K converts analog 
data to digital data and returns the data in a device register. Every 10 
seconds, the program samples 16 to 32 out of 64 channels at gain settings 
that may vary based on the thermocouple type and previous samplings. 


To collect data efficiently, the program buffers data in a process-specified 
interrupt service routine, and requests delivery of an AST to the user process 
when all the requested channels have been sampled. To perform variable 
sampling, the program passes parameters to the interrupt service routine. 
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The program establishes a protocol to communicate between the program 
and the interrupt service routine. The protocol defines a data area shared by 
the main program, the interrupt service routine, and the AST procedure. The 
data area contains parameters from the program and data from the AD11-K. 
The data area is a 98-word array used as follows: 


1 


Elements 1-2 of the data area contain an index to the next buffer location 
to be filled, and a count indicating the number of samplings still to be 
taken. The main program initializes these values before starting the 
device. The interrupt service routine reads and modifies these values in 
the process of copying data and determining when to stop sampling. 


Elements 3-66 of the data area are reserved for interrupt service routine 
parameters. Each pair of elements contains the number of a channel and 
a gain value. The main program loads these parameters before starting 
the device. 


Elements 67-98 of the data area receive the data that the interrupt service 
routine reads from the AD11-K data buffer register. The AST routine 
later reads data from this part of the buffer. 


The program sets up for the sampling as follows: 


1 
2 


6 


7 


Assigns a channel to the device 


Calls the $CRMPSC system service to map to the I/O page in order to 
address the device registers 


Initializes the data area by writing a 67 (the index to the next buffer 
location to be filled) into element 1, and the number of samples to take 
into element 2 of the data area; clears elements 3 through 98 of the data 
area 


Writes channel numbers and gain values into the parameter section of the 
data area | 


Issues a connect-to-interrupt $QIO call to connect the process to the A/D 
converter; specifies the addresses of the area to be double-mapped, an 
offset to the interrupt service routine, and an AST procedure 


Sets the start and interrupt-enable bits in the AD11-K status register to 
start the A/D converter 


Calls the $HIBER system service to place the process in a wait state 


As soon as the AD11-K has converted the first sample, the device generates 
an interrupt. CONINTERR.EXE calls the process-specified interrupt service 
routine. This process-specified routine executes as follows: 


1 


2 


Computes the next location to be written in the buffer by reading the first 
element in the data area 


Reads 12 bits of data from the A/D buffer register into the next location 
in the buffer 


Updates the buffer offset and count elements at the beginning of the data 
area 


If all requested samples have been collected, writes the address of the 
data area into the AST parameter, sets a status flag that will cause an AST 
to be delivered to the control program, and returns to the CONINTERR 
routine 
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5 Otherwise, sets the start bit in a device register to restart the device and 
returns to the CONINTERR routine with a status flag requesting no AST 
delivery or event flag setting 


Based on the interrupt status from the process-specified interrupt service 
routine, the CONINTERR routine completes the interrupt processing by 
queuing a fork process that will queue an AST to the user process. When the 
process gains control in the AST procedure, it processes the samples in the 
following steps: 


1 Clears the interrupt-enable bit in the device status register 


2 Examines the data collected in order to adjust channel selection and/or 
gain values for the next sampling 


3 Copies the data to a file 
Reinitializes the data area 


5 Calls the $5CHDWK system service to wake the process after a short 
interval (for example, 10 seconds) 


6 Returns 
When the time interval elapses, the process regains control. The program 


can then restart the sampling process by again setting the start and interrupt- 
enable bits in the AD11-K status register. 


18.4.3 Example 3: KW11—P Real-Time Clock and AD11—K Converter 
Connected to the UNIBUS 
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This type of device reports asynchronous external events by collecting data: 
one device triggers another device by generating an interrupt that causes a 
programmed request to be sent to the other device, which in turn generates 
an interrupt. A typical example is a clock-driven A/D operation for precise 
time sampling as required in signal processing. This processing technique 
is often used in laboratories. The amount of data collected in such a timed 
sampling might typically be 200 to 1000 16-bit words. 


In this example, the main program sets up the real-time clock to generate 
interrupts periodically. At regular intervals, the clock interrupt triggers a 
programmed request for an A/D conversion operation. The AD11-K collects 
a sample, and interrupts the CPU with a “done” interrupt and 12 bits of 
data. The AD11-K interrupt service routine buffers the data and, if the buffer 
is full, causes an AST to be delivered to the process. The process, gaining 
control in an AST procedure, copies the buffered data to another buffer or to 
disk. 


Programming these device functions is slightly more complicated than the 
previous example. The main program must specify a large buffer to be 
used in ring fashion to guarantee that data is not lost between clock-driven 
samplings. In addition, the program must connect to two device interrupts— 
one for the clock and one for the A/D converter. 


The protocol used by the main program, the interrupt service routine, and the 
AST procedure is similar to the previous example. The data area is larger: 4K 
words of buffer area follow the parameter area. The A/D converter interrupt 
service routine and the AST procedure treat the 4K-word buffer as four buffer 
sections of 1K words per section. The first element in each 1K buffer section 
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is a flag indicating whether the section is in use. The AST resets the flag 
value after copying the contents of the buffer. The interrupt service routine 
uses a buffer section only if the section’s flag value indicates that the buffer 
has been emptied. 


The main program starts the sampling with the following steps: 


1 
2 


9 


Assigns channels to the clock and to the A/D converter. 


Calls the $CRMPSC system service to map to the I/O page in order to 
address the device registers. 


Initializes the data buffer by writing a 67 (the index to the next buffer 
location to be filled) into element 1, and the number of samples to take 
into element 2 of the data area; clears elements 3 through 4096 of the 
data area; flags each page of the buffer as available. 


Writes channel numbers and gain values into the parameter segments of 
the data area. 


Issues a connect-to-interrupt $QIO call to connect the process to the clock, 
and specifies the address of an interrupt service routine. 


Issues a connect-to-interrupt $QIO call to connect the process to the A/D 
converter; and specifies the addresses of the area to be double mapped, 
an offset to the interrupt service routine and an AST procedure. 


Sets the sampling interval by writing a 16-bit value into the KW11-P 
count set buffer register. 


Starts the clock by setting the run, mode, rate selection, and interrupt- 
enable bits in the KW11-P control and status register. Setting the mode 
bit causes repeated interrupts generated at a rate specified in the time 
interval. 


Calls the $HIBER system service to place the process in a wait state. 


The clock interrupts when zero (underflow) occurs during a countdown from 
the preset interval count. The VMS CONINTERR routine calls the process- 
specified clock interrupt service routine. This process-specified routine starts 
the A/D conversion as follows: 


1 


2 


3 


Starts the A/D converter by setting the start and interrupt-enable bits in 
the AD11-K status register 


Sets interrupt status that prevents AST delivery or event flag setting as a 
result of this interrupt 


Returns to CONINTERR 


Starting the A/D converter results in an interrupt from the AD11-K, and 
control passes, by way of CONINTERR, to the AD11-K interrupt service 
routine. This routine executes as follows: 


1 


If this sample is the first sample for a new buffer (indicated by a flag in 
the data area), the routine moves to the next buffer section (branching to 
error handling if the buffer is still full), and sets up the first two elements 
of the data area to indicate the buffer section to be written next. Then it 
sets the flag at the start of the new buffer section and sets a flag in the 
data area to indicate that sampling is occurring. 


The routine computes the next location to be written in the buffer by 
reading the first location in the data area. 
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3 The routine reads 12 bits of data from the A/D buffer register into the 
next location in the buffer. 


The routine updates the buffer offset and count values in the data area. 


5 If this sample fills the data sector, the routine writes the offset of the filled 
sector from the start of the 4K-word buffer into the AST parameter, sets a 
status flag that will cause an AST to be delivered to the control program, 
and sets a flag indicating that a new data section is to be started. 


6 The routine returns to CONINTERR. 


The AST procedure copies and fills the next buffer section with zeros to 
indicate that the section is again available to the interrupt service routine. 
When the next clock interrupt occurs, the data can be written to the next 
buffer section, even if the AST routine has not yet emptied the previous 
buffer section. 


Part IV Reference Section and Examples 
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Data Structures 


Notes: 


This appendix provides a condensed description of those data structures 
referenced by driver code. It lists their fields in the order in which they 
appear in the structures. All data structures discussed in this appendix—with 
the exception of the channel control block (CCB)—exist in nonpaged system 
memory. 


Many of these structures—including the adapter control block (ADP), channel 
control block (CCB), channel request block (CRB), configuration control 
block (ACF), device data block (DDB), driver dispatch table (DDT), driver 
prologue table (DPT), object rights block (ORB), I/O request packet (IRP), 
I/O request packet extension (IRPE), and unit control block (UCB)—are 
collectively known as the I/O database (see Figure A-1). The structures in 
the I/O database help the VMS operating system and device drivers monitor 
the status of, and control the functions of, the I/O subsystem. They provide 
the following types of information: 


¢ Descriptions of each pending and in-progress I/O request 

e Characteristics of each device type | 

¢ Number and type of each device unit 

¢ Status of current activity on each device unit 

e External entry points to all device drivers 

e Entry points for controller and device unit initialization routines 

¢ Code that dispatches interrupts to the appropriate servicing routines 
e Addresses of device registers 


¢ Bit maps describing the allocation of data paths and map registers 


Aside from the I/O database structures, this appendix includes descriptions of 
those data structures VMS uses to maintain multiprocessing synchronization 
and record processor-specific information: the spin lock data structure (SPL) 
and the per-CPU database structure (CPU), respectively. 


Driver code must consider fields marked by asterisks to be read-only 
fields. Fields marked “reserved” or “unused” are reserved for future use 
by DIGITAL unless otherwise specified. 


When referring to locations within a data structure, a driver should use 
symbolic offsets from the beginning of the structure and not numeric 
offsets. Numeric offsets are likely to change with each new release of the 
VMS operating system. The figures in this appendix list VMS Version 5.0 
numeric offsets to aid in driver debugging. ; 
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A.1 Configuration Control Block (ACF) 


Figure A—1 
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Configuration Control Block (ACF) 


The configuration control block (ACF) is used by the SYSGEN 
autoconfiguration facility to describe the device it is adding to the system. 
Device drivers can gain access to this data structure only if they have specified 
a unit delivery routine in the DPT and only when that routine is executing. 
Under certain conditions, the information stored in the ACF might be useful 


to a unit delivery routine. 


The fields described in the configuration control block are illustrated in 
Figure A—2 and described in Table A-1. 
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Figure A—2 Configuration Control Block (ACF) 
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Table A—1 Contents of the Configuration Control Block 


Field Name 


ACF$L_ADAPTER* 
ACF$L__CONFIGREG* 
ACFSW_AVECTOR* 
ACF$B_AUNIT* 
ACF$B_AFLAG* 


ACF$L_—CONTRLREG* 
ACF$W_CVECTOR* 


ACF$B_CUNIT* 
ACF$L_DEVNAME* 


ACF$L_DRVNAME* 


ACFSW_MAXUNITS* 


ACF$B_CNUMVEC* 
ACF$B_COMBO_VEC* 


ACF$B_COMBO_CSR* 


ACF$B_NUMUNIT* 
ACF$L_DLVR_SCRH 


Contents 


Address of ADP for adapter currently being configured. 

Address of configuration register for adapter currently being configured. 

Offset from base of SCB to interrupt vector of adapter currently being configured. 
Adapter unit number of device or controller currently being configured. 


Flags associated with autoconfiguration operation. Flags defined in this field 
include the following: 


ACF$V_RELOAD 
ACF$V_CRBBLT 
ACF$V_SCBVEC 
ACF$V_NOLOAD_DB 
ACF$V_SUPPORT 
ACF$V_GETDONE 


Reloading driver code. 

CRB and IDB already built for device. 
CVECTOR is offset into SCB. 

Do not load |/O database, only load driver. 
VMS-supported device. 


Addresses of data structures in I/O database have been 
obtained. 

ACF$V_BVP Multiport BVP adapter. 
Address of CSR for controller currently being configured. 


Offset into ADP vector table to longword that contains transfer address of 
interrupt vector used by controller currently being configured (if ACF$V_SCBVEC 
is not set). If ACF$V_SCBVEC is set, this field is the offset from the SCB base to 
the interrupt vector of the controller currently being configured. 


Unit number of device currently being configured. 


Address of counted ASCII string that gives name of controller currently being 
configured. 


Address of counted ASCII string that gives driver name for controller currently 
being configured. . 


Maximum number of units that can be connected to controller currently being 
configured. 


Number of interrupt vectors to configure for controller currently being configured. 


Offset to vectors for combo device. (The name of this field is ACF$B_COMBO_ 
VECTOR_OFFSET.) 


Offset to start of control registers of combo device. (The name of this field is 
ACF$B_COMBO_CSR__OFFSET.) 


Number of units to be configured for controller currently being configured. 
Field available for use by unit delivery routine. SYSGEN never alters this field. 





Adapter Control Block (ADP) 


Each MASSBUS adapter, UNIBUS adapter, Q22 bus, and VAXBI node 
configured in a VAX system is represented to VMS and driver routines by 
an adapter control block (ADP). The ADP stores adapter-specific static and 
dynamic data such as the adapter CSR address and map-register wait queues. 
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The ADP varies in size, depending upon what type of adapter it describes. 


Table A-2 defines those fields that generally appear in an ADP. 


Figure A—3 Adapter Control Block (ADP) 
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Table A—2 Contents of Adapter Control Block 


Field Name 


ADP$L_CSR* 


ADPS$L _LINK* 


ADP$W-_SIZE* 


ADP$B_TYPE* 


ADP$B_NUMBER* 


ADP$W_TR* 


ADP$W__ADPT YPE* 


Contents 


Virtual address of adapter configuration register. For a generic VAXBI adapter, 
this field contains the address of the base of the adapter’s node space. The 
VMS adapter initialization routine writes this field. 


The configuration register marks the base of adapter register space, an 
area that contains data path registers, map registers, or any other registers 
appropriate to the implementation of the adapter. 


Address of next ADP. The VMS adapter initialization routine writes this field. 
A value of O indicates that this is the last ADP. 


Size of ADP. The VMS adapter initialization routine writes this field when the 
routine creates the ADP. For non-direct-vector UNIBUS adapters, ADP$W_. 
SIZE includes the space allocated for the four UNIBUS interrupt service routines 
(for BR4 to BR7) and the vector jump table. 


Type of data structure. The VMS adapter initialization routine writes the 
symbolic constant DYN$C_ADP into this field when the routine creates the 
ADP. 


Number of this type of adapter (for example, the number for a third MASSBUS 
adapter is 2). The VMS adapter initialization routine writes this field when the 
routine creates the ADP. 


Nexus number of adapter. The VMS adapter initialization routine writes this 
field when the routine creates the ADP. The driver-loading procedure compares 
the nexus number specified in a CONNECT command with this field of each 
ADP in the system to determine to which adapter a device is attached. For a 
generic VAXBI adapter, this field contains its VAXBI node ID. 


Type of adapter. The VMS adapter initialization routine writes the symbolic 
constant AT$_UBA into this field when the routine creates an ADP for a 
UNIBUS adapter or Q22 bus; AT$_MBA for a MASSBUS adapter; and AT$_ 
GENBI for a generic VAXBI adapter. 


Table A—2 (Cont.) 


Field Name — 


ADP$L_VECTOR* 


ADP$L_DPOFL* 


ADP$L_—DPOBL* 


ADP$L_AVECTOR* 
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Contents of Adapter Control Block 


Contents 


Address of adapter dispatch table. The table is 512 bytes of longword vectors 
that correspond to device interrupt vectors (Og—777s). 


On VAX processors that handle direct-vector interrupts, ADP$L_VECTOR 
points to the second (or subsequent) page of the SCB. The CPU uses this page 
when it dispatches the device interrupt to the driver interrupt service routine. 
Each vector entry that corresponds to a vector in use contains the address of 
the controller's interrupt dispatcher (CRB$L_INTD). (The actual stored value 

is CRB$L_INTD+1, the set low bit of the address indicating that the interrupt 
stack is to be used in servicing interrupts.) 


On VAX processors that handle non-direct-vector interrupts, ADP$L_.VECTOR 
points to a page allocated from nonpaged pool called the adapter dispatch 
table (or vector jump table). Each longword in the page that corresponds to 

a vector in use contains the address of the controller's interrupt dispatcher 
(CRB$L_INTD+2). When the UNIBUS adapter interrupts on behalf of a UNIBUS 
device, the UNIBUS adapter interrupt service routine saves RO through R65, 
determines the vector address of the interrupting device, indexes into the 
vector-jump table, and jumps to the instruction at CRBSL_INTD+2. 


For both types of VAX processor, adapter dispatch table entries that 
correspond to unused vectors contain the address of the adapter’s unexpected- 
interrupt service routine. 


Data path wait queue forward link. IOC6REQDATAP and IOCSRELDATAP read 
and write this field. When a driver fork process requests a buffered data path 
and none is currently available, IOCSREQDATAP saves driver context in the 
device’s UCB fork block, inserts the fork block address in the data path wait 
queue, and suspends the driver fork process. 


When another driver calls IOC6RELDATAP to release a buffered data path, the 
routine dequeues a UCB fork block address from the data path wait queue, 
allocates a data path to the driver, and reactivates that driver fork process. 


This field is also known as ADP$L_MBASCB. For MASSBUS adapters and 
generic VAXBI adapters, the VMS adapter initialization routine stores the 
address of the adapter’s interrupt vector in this field. Certain power failure 
recovery operations use the contents of ADP$L_MBASCB to refresh the SCB 
vectors. The actual stored value is CRB$L_INTD+1, the set low bit of the 
address indicating that the interrupt stack is to be used in servicing interrupts. 


Data path wait queue backward link. IOCSREQDATAP and lIOC$RELDAT AP 
read and write this field. 


This field is also known as ADP$L_MBASPTE. For generic VAXBI adapters, 
the VMS adapter initialization routine stores here the contents of the first of 
16 SPTEs that map the adapter’s node space. For the MASSBUS adapter, the 
routine stores here the SPTE value that maps MBA address space. Certain 
recovery operations use the contents of ADP$L_MBASPTE to restore SPTE 
values and remap node space following a power failure. 


Address of first SCB vector for adapter. 


Data Structures 
A.2 Adapter Control Block (ADP) 


Table A—2 (Cont.) Contents of Adapter Control Block 
Field Name Conterts 


ADP$L _Bl_IDR* Longword mask specifying, by a single set bit, which VAXBI node is the 
destination of interrupts from this adapter. In VAX 8200/8250/8300/8350 
systems, the VAXBI node of the primary processor becomes the destination 
for interrupts; in VAX 8530/8550/8700/8800/8830/8840 and VAX 6200- 
series systems, it is the VAXBI node at which the memory-interconnect-to- 
VAXBI adapter (NBIB, PBIB, or DWMBA/B) resides. 


ADP$W_BI_FLAGS*« VAXBI device flags field. 

ADP$W_BI_VECTOR* Offset of the first interrupt vector for this VAXBI node from the start of its 
SCB page. ADP$L_AVECTOR contains the address of this vector. 

ADP$L__SCB_PAGE* Offset to SCB page for this VAXBI device. 

ADP$L_BIMASTER* Address of the ADP of the master device of the VAXBI (for example, the 
DWMBA in a VAX 6200-series system). 

ADP$W_ADPDISP_ Flags used by the ADPDISP macro to control branching according to adapter 

FLAGS* characteristics. The following bit fields are defined within ADP$W_ADPDISP_ 
FLAGS: 
ADP$V_ADPDISP_INIT ADPDISP flags have been initialized 


ADP$V_ADAP_MAPPING Adapter mapping supported 
ADP$V_DIRECT_VECTOR __ Direct-vector interrupts 
ADP$V_AUTOPURGE_DP  Autopurging datapath 

ADP$V_BUFFERED__DP Buffered datapath supported 
ADP$V_ODD_XFER_BDP Odd transfers supported on buffered data path 
ADP$V_ODD_XFER_DDP Odd transfers supported on direct data path 


ADP$V_EXTENDED_ Alternate map registers (registers 496 to 8191) 
MAPREG supported 
ADP$V_OBUS Q22 bus adapter 
<15:9> Reserved to DIGITAL 

ADP$B_.ADDR_BITS* Number of adapter address bits. This field contains the value 22 (for Q22 bus 
systems) and 18 (for UNIBUS adapters). 

ADP$L_MROFL* _ Standard-map-register wait queue’s forward link. IOC6ALOUBAMAP, 


IOC$REQMAPREG, and IOC$RELMAPREG read and write these fields. When a 
driver fork process requests a set of standard map registers and the set is not 
currently available, (OCSREQMAPREG saves driver fork context in the device's 
UCB fork block, inserts the fork block address in the standard-map-register 
wait queue, and suspends the driver fork process. 


When another driver calls IOCS6RELMAPREG to release a set of standard map 
registers, the routine dequeues a UCB fork block address from the standard- 
map-register wait queue, allocates the requested set of map registers to the 
driver, and reactivates that driver fork process. 


ADP$L_—MROBL* Standard-map-register wait queue’s backward link. IOC6ALOUBAMAP, 
IOCSREQMAPREG, and |OC$RELMAPREG read and write this field. 
ADP$L _INTD* Interrupt transfer vector. The VMS adapter initialization routine places 


executable code in this field to allow certain DIGITAL-supplied adapters or 
controllers to dispatch to adapter-specific interrupt and error handling routines. 
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Table A-—2 (Cont.) Contents of Adapter Control Block 


Field Name 
ADP$L__UBASCB* 


ADP$L_UBASPTE* 


ADP$L_MRACTMDRS* 


ADP$W_DPBITMAP* 


ADP$W._MRNFENCE* 


ADP$W_MRNREGARY* 


ADP$W_MRFFENCE* 
ADP$W_MRFREGARY* 


ADP$W_UMR_DIS* 


Contents 


Series of four longwords that contain SCB entry values, one for each bus 
request (BR) level or interrupt vector. The UNIBUS adapter power failure 
recovery procedure uses these values. 


System page-table entry (PTE) values for base of UNIBUS adapter register 
space and base of UNIBUS 1/O register space. These values contained in this 
quadword field ar2 used during UNIBUS adapter power failure recovery. 


Number of active standard map register descriptors in arrays to which 
ADP$W_MRNREGARY and ADP$W_MRFREGARY point. |OCSREQMAPREG 
and IOC$RELMAPREG use these fields when allocating and deallocating 
standard map registers. . 


Data path allocation bit map. IOC6REQDATAP and IOC$RELDATAP read and 
write this field. The VMS adapter initialization routine sets the bit map to show 
as available all the buffered data paths supported by the UNIBUS adapter. 
(The adapter initialization routine for certain VAX processors whose UNIBUS 
adapters or Q22 bus interfaces do not supply buffered data paths marks three 
data paths as available. This facilitates the writing of machine-independent 
code that can execute regardless of the presence of buffered data paths.) 


The state of each of the available buffered data paths (whether in use or 
available) is recorded in the data path allocation bit map. One data path 
corresponds to each bit in the field. If a bit is clear, the related data path is 
currently allocated to a driver fork process. 


Boundary marker for the array specified by ADP$W_MRNREGARY; 
contains —1. 


Standard map register “number of registers” array of 124 words. The number 
of words, or cells, that are active in this array is contained in ADP$L_ 
MRACTMDRS. Each active cell gives the number of free standard map 
registers. For each active cell in this array, there is a corresponding first 

free map register number in the “first register” array (ADP$W_HMRFREGARY). 
Together, these values give the base map register and number of free map 
registers for a block of free map registers. This information is used to allocate 
and deallocate standard map registers. 


Boundary marker for array specified by ADP$W_MRFREGARY; contains —1. 


Standard map register “first register” array of 124 words. The number of 
currently active cells in this array is contained in ADP$L_MRACTMDRS. Each 
active cell gives a number of the first free map register within a block of free 
map registers. For each active cell in this array, there is a corresponding cell in 
the “number of registers” array (ADP$W_MRNREGARY) that gives a number 
of free map registers. Together, these values give the base map register 

and number of free map registers for a block of free map registers. This 
information is used to allocate and deallocate standard map registers. 


Number of disabled standard map registers. During system initialization, some 
standard map registers can be disabled so that their corresponding UNIBUS 
and O22 bus addresses can be accessed directly through UNIBUS-space or 
Q22-bus-space physical addresses. 
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Table A—2 (Cont.) Contents of Adapter Control Block 


Field Name 
ADP$L_MR2QFL* 


ADP$L_—MR2QBL* 


ADP$L_MR2ACTMDR* 


ADP$W_MR2NFENCE* 


ADP$W_MR2NREGAR* 


ADP$W_MR2FFENCE* 


ADP$W.__MR2FREGAR* 


ADP$W_UMR2_DIS* 


ADP$L_MR2ADDR 
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Contents 


Alternate-map-register wait queue’s forward link. IOC6ALOALTMAP, 
IOCS$REQALTMAP, and IOCSRELALTMAP read and write this field. When 

a driver fork process requests a set of Q22 bus alternate map registers and 
the set is not currently available, IOC6REQALTMAP saves driver context in the 
device's UCB fork block, inserts the fork block address in the alternate-map- 
register wait queue, and suspends the driver fork process. 


When another driver calls IOCSRELALTMAP to release a sufficient number of 
map registers, the routine dequeues a UCB fork block from the alternate-map- 
register wait queue, allocates the requested set of map registers to the driver, 
and reactivates that driver fork process. 


Alternate-map-register wait queue’s backward link. IOCBALOALTMAP, 
lIOCSREQALTMAP, and IOC$RELALTMAP read and write this field when. 
allocating and deallocating from the set of Q22 bus alternate map registers. 


Number of active map register descriptors in arrays to which ADP$W_ 
MR2NREGAR and ADP$W_MR2FREGAR point. |OC6ALOALTMAP, 
IOCSREQALTMAP, and IOC$RELMAPREG use these fields when allocating 
and deallocating Q22 bus alternate map registers. 


Boundary marker for the array specified by ADP$W_MR2NREGAR; 
contains —1. 


Alternate-map-register “number of registers” array of 124 words. The number 
of words, or cells, that are active in this array is contained in ADP$L_ 
MR2ACTMDR. Each active cell gives a number of map registers in a block 

of free alternate map registers. For each active cell in this array, there is 

a corresponding first free map register number in the array specified by 
ADP$W_MR2FREGAR. Together, these values give the base map register 
and the number of free map registers for a block of free alternate map 
registers. IOCS6ALOALTMAP, IOC$REQALTMAP, and IOC$RELALTMAP 

use this information when allocating and deallocating from Q22 bus alternate 
map registers. 


Boundary marker for the array specified by ADP$W_MR2NREGAR; 
contains —1. 


Alternate map register “first register” array of 124 words. The number 

of words, or cells, that are active in this array is contained in ADP$L_ 
MR2ACTMDR. Each active cell gives the number of the first free map register 
within a block of free map registers. For each active cell in this array, there is 
a corresponding cell in the “number of registers” array, ADP$W_MR2NREGAR. 
Together, these values give the base map register and the number of free map 
registers for a block of free map registers. 


Number of disabled O22 bus alternate map registers. During system 
initialization, some map registers can be disabled so that their corresponding 
Q22 bus addresses can be accessed directly through physical addresses. 


Address of the first Q22 bus alternate map register mapped in CPU node 
private space. The value varies for each processor with alternate map 
registers. IOCS6LOADUBAMAP reads this field when accessing alternate 
map registers. © 
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A.3 Channel Control Block (CCB) 


When a process assigns an I/O channel to a device unit with the $ASSIGN 
system service, EXES$ASSIGN locates a free block among the process’s 
prealiocated channel control blocks (CCBs). EXE$ASSIGN then writes into 
the CCB a description of the device attached to the CCB’s channel. 


The channel control block is the only data structure described in this appendix 
that exists in the control (P1) region of perprocess address space. It is 
illustrated in Figure A—4 and described in Table A-3. 


Figure A—4 Channel Control Block (CCB) 
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Table A-3 Contents of Channel Control Block 


Field Name 


CCBS$L__UCB* 


CCB$L_WIND* 


CCB$B_STS* 
CCB$B_AMOD+ 


CCBSW_1OC* 


CCBS$L_DIRP* 


Contents 


Address of UCB of assigned device unit. EXESASSIGN writes a value into this 
field. EXE$QIO reads this field to determine that the |/O request specifies a 
process |/O channel assigned to a device and to obtain the device’s UCB address. 


Address of window control block (WCB) for file-structured device assignment. 
This field is written by an ACP or XOP and read by EXES$OIO. 


A file-structured device’s XOQP or ACP creates a WCB when a process accesses 
a file on a device assigned to a process I/O channel. The WCB maps the virtual 
block numbers of the file to a series of physical locations on the device. 


Channel status. 


Access mode plus 1 of the channel. EXESASSIGN writes the access mode value 
into this field. 


Number of outstanding |/O requests on channel. EXE$QOIO increases this field 
when it begins to process an I/O request that specifies the channel. During 1/O 
postprocessing, the special kernel-mode AST routine decrements this field. Some 
FDT routines and EXESDASSGN read this field. 


Address of IRP for requested deaccess. A number of outstanding |/O requests 
can be pending on the same process I/O channel at one time. If the process that 
owns the channel issues an |/O request to deaccess the device, EXE$QIO holds 
the deaccess request until all other outstanding I/O requests are processed. 
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Per-CPU Database (CPU) 
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A per-CPU database structure exists for each processor in a VMS 
multiprocessing environment. The per-CPU database records processor- 
specific information such as the current process control block (PCB), the 
priority of the current process, and the physical processor identifier. It 
points to the processor’s interrupt stack and contains the list heads for the 
processor’s fork queues and I/O postprocessing queue. 


To ensure that the path of a processor’s activity at booting and on the 
interrupt stack remains independent of the paths of other active processors in 
the system, VMS places a separate boot stack and a separate interrupt stack 
(formerly pointed to by EXESGL—INTSTK) adjacent to the area allocated 

for the per-CPU database structure. The processor's boot stack, interrupt 
stack, and per-CPU database fields are virtually contiguous in system address 
space, although three no-access guard pages prevent the expansion of the 
stacks beyond the areas reserved for their use. Offset CPU$L_INTSTK in the 
per-CPU database points to the interrupt stack. 


The fields described in the per-CPU database are illustrated in Figure A-5 
and described in Table A-4. 
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Figure A-5 Per-CPU Database (CPU) 













; 
. 
: 
; 
; 
: 
, 
: 
: 
: 
CPU$L_SAVED_ISP* 40 

CPUSL_PCBB* 44 


CPU$L—SCBB* 48 


CPUS$L _SISR* 52 
CPUSL__POBR* 56 
CPU$L_POLR* 60 
CPU$L_P 1BR* 64 
CPU$L_P 1LR* 68 


CPU$L__BUGCODE* 72 


CPU$B_CPUDATA+ (32 bytes) 76 





CPU$L_—MCHK_MASK+ 108 


CPU$L__MCHK_SP* 112 


CPU$SL_POPT_PAGE* 116 


reserved (408 bytes) 120 





CPU$Q__SWIOFL+ (48 bytes) 528 


CPU$L_PSFL* 576 
CPUS$L_PSBL* 580 


CPU$Q_WORK_FOFL* 584 


CPU$L_OLOST_FOFL* 592 


CPU$L_OQLOST_FOBL* 596 


CPU$B_QLOST_FLCK* | CPU$B_OLOST_T YPE* CPU$W_QLOST_SIZE* 600 
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Figure A—5 (Cont.) Per-CPU Database (CPU) 
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. CPU$L_QLOST_FPC* 
CPU$L_QLOST_FR3* 
CPU$L_OQLOST_FR4* 


CPU$Q__BOOT_TIME* 
CPU$Q _CPUID_MASK* 


CPU$L_KERNEL* (28 bytes) 


CPUSW__UKERNEL* (14 bytes) 


CPU$L_IPL__ARRAY* (128 bytes) 


CPU$L_TPOINTER* 
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640 
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696 
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CPU$W-_SANITY_TICKS* CPU$W_SANITY_TIMER* 
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Table A—4 Per-CPU Database (CPU) 





Field 


Contents 





CPUS$SL__CURPCB* 
CPUS$L__REALSTACK* 
CPU$W_SIZE* 


CPU$SB_TYPE* 


CPU$B_SUBT YPE* 
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Address of current PCB. The scheduler writes this field. 
Physical address of boot stack. 


Size of the per-CPU database, including the size of the boot stack but not the 
interrupt stack or the interrupt stack’s guard pages. 


Type of data structure. VMS writes the value DYN$C_MP into this field when 
it creates the per-CPU database. 


Structure subtype. VMS writes the value DYN$C_MP_CPU into this field when 
it creates the per-CPU database. 


Table A—4 (Cont.) 
Field 
CPU$B_STATE* 


CPU$B_CPUMT X* 
CPU$B_CUR_PRI*: 
CPU$SL_INTSTK* 
CPUSL_—WORK _REQ* 


CPUSL__PERCPUV A* 
CPU$L_SAVED_.AP* 
CPU$L__HALTPC* 
CPU$L_HALTPSL* 
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Per-CPU Database (CPU) 


Contents 


State of this processor. VMS defines the following processor states: 


CPU$C_INIT Processor is being initialized. 

CPU$C_RUN Processor is running. 

CPU$C_STOPPING Processor is stopping. 

CPU$C_STOPPED Processor is stopped. 

CPU$C_TIMOUT Logical console has timed out. 

CPU$C_BOOT_REJECTED Processor has refused to join multiprocessing 
system. 

CPU$C_BOOTED Processor has booted, but is waiting to join 


multiprocessing active set. 
Count of acquisitions of CPUMTX mutex. 
Current process priority. The scheduler writes this field. 
Address of initial interrupt stack. 


Work request bits. A processor sets one or more of these bits in another 
processor's per-CPU database when directing an interprocessor interrupt to 
that processor. 


The following fields are defined within CPU$L__WORK __REQ: 


CPU$V_INV_TBS Request to invalidate single address (SMP$GL _ 
INVALID) in translation buffer 

CPU$V_INV_TBA Request to invalidate all addresses in translation 
buffer 

CPU$V_TBACK Acknowledgment that a processor requested to 
invalidate its translation buffer has done so 

CPU$V_BUGCHK Request to bugcheck 


CPU$V_BUGCHKACK Acknowledgment that the processor has saved 
process context and per-CPU data so that the crash 
CPU can continue to perform a bugcheck 


CPU$V_RECALSCHD Recalculate per-CPU mask and reschedule 


CPU$V_UPDASTLVL Request to update processor AST level register 
(PRS6_ASTLVL) 


CPU$V_UPDTODR Request to update processor time-of-day register | 
(PR$_TODR) 

CPU$V_WORK_FOP Request to process internal fork queue (CPU$O _ 
WORK _IFQ) 

CPU$V_OLOST Request to stall until quorum regained 

CPU$V_RESCHED Request to initiate software interrupt at IPL 3 

CPU$V_VIRTCONS Request to enter virtual console mode 

<28:31> Processor-specific work request bits 


Virtual address of this per-CPU database structure. 
Halt restart code. 

Halt PC for restart. 

Halt PSL for restart. 
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Table A—4 (Cont.) Per-CPU Database (CPU) 


Field 
CPU$L__SAVED_ISP* 
CPUSL_—PCBB* 
CPU$L_SCBB* 
CPUS$L _SISR* 
CPU$L_POBR* 
CPUSL_POLR* 
CPU$L__P1BR* 
CPU$L_P 1LR* 
CPU$L_BUGCODE* 
CPUSB_CPUDATA* 


CPU$L_MCHK _MASK* 
CPU$L_—MCHK _SP* 


CPU$L__POPT_PAGE* 
CPU$Q_SWIQFL* 


CPU$L__PSFL* 
CPU$L_PSBL* 
CPU$Q_WORK_FOFL* 
CPU$L_OLOST_FOFL* 
CPU$L__OLOST_FOBL* 
CPU$W_OLOST_SIZE* 
CPU$B_QLOST_TYPE* 
CPU$B_QLOST_FLCK* 
CPU$L_QLOST_FPC* 
CPU$L_QLOST_FR3* 
CPU$L__OLOST_FR4* 
CPU$Q_BOOT_TIME* 
CPU$Q _CPUID_MASK* 
CPU$L_PHY_CPUID* 
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Contents 


Saved ISP for restart. 

PCBB from power down. 

SCBB from power down. 

SISR from power down. 

PO base register (used by system power failure and bugcheck routines). 
PO length register (used by system power failure and bugcheck routines). 
P1 base register (used by system power failure and bugcheck routines). 
P1 length register (used by system power failure and bugcheck routines). 
Bugcheck code. 


Processor-specific hardware revision information. The first longword of this 
16-byte field always contains the processor’s system ID (SID) register, and is 
also defined as CPU$L_SID. 


Function mask for current machine check recovery block. 


Saved SP for return at end of machine check recovery block. This field is zero 
if there is no current recovery block. 


System virtual address of a page reserved to this processor that is used as a 
PO page table when memory management is being enabled. 


Twelve longwords representing the forward and backward links for the 
software interrupt queues (fork IPLs 6 through 11). 


1/O postprocessing queue forward link. 

1/O postprocessing queue backward link. 

Work packet queue. This field is also called CPU$Q_.WORK_IFQ. 
Quorum loss fork queue forward link. 

Quorum loss fork queue blink link. 

Quorum loss fork block size. 

Quorum loss fork block type. 

Quorum loss fork lock. 

Quorum loss fork PC. 

Quorum loss fork R3. 

Quorum loss fork R4. 

System time at which this processor was bootstrapped. 
Bit mask representing this processor's CPU ID. 


Integer that uniquely identifies the local processor in a multiprocessor 
configuration. This value is system specific. (For example, ina VAX 
8300/8350 configuration, it is the VAXBI node ID. For a VAX 8800, it is 
the left or right bit from the processor's system ID register (PR$_SID); for 

a VAX 8830/8840 it is the CPU number (0 to 3) from PR$_SID. In a VAX 
6200-series configuration, it is the XMI node ID. VMS uses the physical ID 
principally to locate the per-CPU database and interrupt stack of a processor 
that it is restarting.) 
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Table A—4 (Cont.) 
Field 
CPU$L_—_CAPABILITY* 


CPU$L_—TENUSEC* 
CPU$L_UBDELAY* , 
CPU$L_KERNEL* 


CPU$L_NULLCPU* 


CPU$W-_UKERNEL* 
CPU$W_UNULLCPU* 
CPU$W_.CLKUTICS« 
CPU$W_HARDAFF*« 
CPU$L_RANK_VEC* 


CPU$L_IPL_VEC* 


CPU$L_IPL_ARRAY* 


CPU$L_TPOINTER* 


CPUSW_SANIT Y_TIMER* 
CPU$W_SANIT Y_TICKS* 
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Per-CPU Database (CPU) 


Contents 


Bit mask of this processor's capabilities. 


VMS defines the following capabilities in $CPBDEF: 
CPB$C_PRIMARY Primary CPU. 


CPB$C_NS Reserved to DIGITAL. 
CPB$C_QUORUM Quorum required. 
CPB$C_.HARDAFF 
10-microsecond delay value. 
UNIBUS delay counter. 


Set of seven longwords that tally the processor's clock ticks in kernel mode, 
in executive mode, in supervisor mode, in user mode, on the interrupt stack, in 
compatibility mode, and in kernel-mode spin-lock busy-wait state, respectively. 


Hard affinity. Reserved for diagnostics software. 


Clock ticks during which the null job has been the current process on this 
processor. 


Reserved to DIGITAL. 
Reserved to DIGITAL. 
Reserved to DIGITAL. 
Count of processes with hard affinity for this processor. 


Longword recording the ranks of all spin locks currently held by the processor. 
Spin lock acquisition code issues a Find First Set (FFS) instruction on this 
longword to determine if the processor holds any locks that are lower ranked 
than the one it seeks. 


Vector recording, in inverse order, the IPLs of all spin locks currently held by 
the processor (that is, bit O represents IPL 31). 

Array of 32 longwords, corresponding in inverse order to the 32 IPLs (that 
is, the first longword represents IPL 31). Upon each successful spin lock 
acquisition by this processor, the IPL vector corresponding to the spin lock’s 
synchronization IPL (SPL$B_IPL) is incremented. 

Address of the sanity timer (CPUSW_SANITY_TIMER) of the active processor 
with the next highest CPU ID. 


Number of sanity cycles before this processor times out. 


Number of clock ticks until the next sanity cycle. 





Channel Request Block (CRB) 


The activity of each controller in a configuration is described in a channel 
request block (CRB). This data structure contains pointers to the wait queue of 
drivers ready to gain access to a device through the controller. It also stores 
the entry points to the driver’s interrupt service routines and unit/controller 
initialization routines. 


The channel request block is illustrated in Figure A~6 and described in 
Table A-5. | 


A-17 


Data Structures 
A.5 Channel Request Block (CRB) 


A-18 


Figure A-6 Channel Request Block (CRB) 


CRB$B_UNIT_BRK* CRB$W_REFC* 


CRB$L_AUXSTRUC 














20 


24 


28 


32 


36 


40 
CRB$L__TIMELINK* 44 
CRB$L_DUETIME* 48 
CRB$L_TOUTROUT* 52 
CRB$L_LINK« 56 
CRB$L _DLCK+ 


CRB$L_—BUGCHECK* 


CRB$L_RTINTD* (12 bytes) 


CRBS$L_INTD* (40 bytes) 


CRB$L_—BUGCHECK2* 


CRB$L_RTINTD2* (12 bytes) 124 


| CRB$L_INTD2+ (40 bytes) 136 
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Table A—5 Contents of Channel Request Block 


Field Name 
CRB$L_FOFL 


CRB$L_FOBL 
CRB$W_SIZE* 


CRB$B_TYPE* 


CRB$B_FLCK 


CRB$L_FPC 


CRB$L_FR3 


CRB$L_FR4 


CRB$L_WOFL* 


CRB$L_—WOBL* 


CRB$B_TT_TYPE* 


CRB$SW_REFC* 


Contents 


Fork queue forward link. The link points to the next entry in the fork queue. 


Controller initialization routines write this field when they must drop IPL to utilize 
certain executive routines, such as those that allocate memory, that must be 
called at a lower IPL. The CRB timeout mechanism also uses the CRB fork block 
to lower IPL prior to calling the CRB timeout routine. 


Fork queue backward link. The link points to the previous entry in the fork queue. 


Size of CRB. The driver-loading procedure writes this field when it creates the 
CRB. 


Type of data structure. The driver-loading procedure writes the symbolic constant 
DYN$C_CRB into this field when it creates the CRB. 


Fork lock at which the controller's fork operations are synchronized. If it must use 
the CRB fork block, a driver either uses a DPT_STORE macro to initialize this field 
or explicitly sets its value within the controller initialization routine. 


Address of instruction at which execution resumes when the VMS fork dispatcher 
dequeues the fork block. EXESFORK writes this field when called to suspend 
driver execution. 


Value of R3 at the time that the executing code requests VMS to create a fork 
block. EXESFORK writes this field when called to suspend driver execution. 


Value of R4 at the time that the executing code requests VMS to create a fork 
block. EXE$FORK writes this field when called to suspend driver execution. 


Controller data channel wait queue forward link. IOC6REQxCHANy and 
lIOCSRELxCHAN insert and remove driver fork block addresses in this field. 


A channel wait queue contains addresses of driver fork blocks that record 

the context of suspended drivers waiting to gain control of a controller data 
channel. If a channel is busy when a driver requests access to the channel, 
IOCSREQxCHANy suspends the driver by saving the driver's context in the 
device's UCB fork block and inserting the fork block address in the channel wait 
queue. 


When a driver releases a channel because an I/O operation no longer needs the 
channel, IOC$RELxCHAN dequeues a driver fork block, allocates the channel to 
the driver, and reactivates the suspended driver fork process. If no drivers are 
awaiting the channel, IOCSRELxCHAN clears the channel busy bit. 


Controller channel wait queue backward link. IOC$REQxCHANy and 
IOC$RELxCHAN read and write this field. 


Type of controller (for instance, DZ11 or DZ32) for terminals. A terminal port 
driver fills in this field. 


UCB reference count. The driver-loading procedure increases the value in this field 
each time it creates a UCB for a device attached to the controller. 
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Table A—5 (Cont.) Contents of Channel Request Block 


Field Name 
CRB$B_MASK* 


CRB$B_UNIT_BRK*« 
CRB¢L__AUXSTRUC 


CRB$L_TIMELINK* 


CRB$L_DUETIME* 


CRB$L_TOUTROUT* 


CRB$L _LINK* 
CRB$L_DLCK* 


CRB$L__BUGCHECK* 


CRB$L_RTINTD* 
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Contents 


Mask that describes controller status. 


The following fields are defined in CRB$B_MASK: 

CRB$V_BSY Busy bit. IOCSREQxCHANy reads the busy bit to 
determine whether the controller is free and sets this 
bit when it allocates the controller data channel to a 
driver. IOCSRELxCHAN clears the busy bit if no driver is 
waiting to acquire the channel. 


CRB$V_UNINIT Indication, when set, that the VMS adapter initialization 
routine has created a CRB for a generic VAXBI device, 
but has not yet called its controller initialization routine. 
SYSGEN reads this bit to determine whether to call the 
controller initialization routine and clears it when the 
initialization routine completes. This facilitates SYSGEN’s 


processing of multiunit generic VAXBI devices. 
Break bits for terminal lines. Used by VMS terminal port drivers. 


Address of auxiliary data structure used by device driver to store special controller 
information. A device driver requiring such a structure generally allocates a block 
of nonpaged dynamic memory in its controller initialization routine and places a 
pointer to it in this field. 


Forward link in queue of CRBs waiting for periodic wakeups. This field points to 
the CRB$L_TIMELINK field of the next CRB in the list. The CRB$L_TIMELINK field 
of the last CRB in the list contains zero. The listhead for this queue is IOC$GL_ 
CRBTMOUT. Use of this field is reserved to DIGITAL. 


Time in seconds, relative to EXE$GL_ABSTIM, at which next periodic wakeup 


associated with the CRB is to be delivered. Compute this value by raising IPL 

to IPL$_POWER, adding the desired number of seconds to the contents of 
EXE$GL_ABSTIM, and storing the result in this field. Use of this field is reserved 
to DIGITAL. 


Address of routine to be called at fork IPL (holding a corresponding fork lock 

if necessary) when a periodic wakeup associated with CRB becomes due. The 
routine must compute and reset the value in CRB$L_DUETIME if another periodic 
wakeup request is desired. Use of this field is reserved to DIGITAL. 


Address of secondary CRB (for MASSBUS devices only). This field is written by 
the driver-loading procedure and read by IOC6REQSCHANx and IOC$RELSCHAN. 


Address of controller’s device lock. The driver-loading procedure initializes this 
field and propagates it to each UCB it creates for the device units associated with 
the controller. 


Bugcheck data used to issue an ILLOBUSCFG bugcheck when the multilevel 
interrupt dispatching code (at CRB$L_RTINTD) determines that a Q22 bus is 
illegally configured. 


Portion of interrupt transfer vector created at system initialization when a 
MicroVAX 3600-series system or MicroVAX Il system implements multilevel 
device interrupt dispatching. The code stored in this 12-byte field implements 
a conditional lowering to device IPL. See Figure A~7 and Table A-6 for a 
description of the contents of the interrupt transfer vector. 


Table A—5 (Cont.) 
Field Name 


CRB$L_INTD* 


CRB$L_BUGCHECK2* 


CRB$L_RTINTD2+ 


CRB$L_INTD2+ 
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Contents of Channel Request Block 


Contents 


Interrupt transfer vector. This 10-longword field (described in Figure A—7 

and Table A-—6) stores executable code, driver entry points, and I/O adapter 
information. It contains pointers to the driver's controller and unit initialization 
routines, the interrupt dispatch block (IDB), and the adapter control block (ADP). 
It may also contain fields that describe the disposition of a controller's data paths 
and map registers. The interrupt transfer routine is located at the top of the 
interrupt transfer vector. 


Although certain of the symbolic offsets defined in the data structure definition 
macro $VECDEF have negative values, driver code can uniformly refer to the 
contents of the VEC structure in the following form: 


CRB$L __INTD+VEC$x_symbol. 


Bugcheck data used to issue an ILLQBUSCFG bugcheck when the multilevel 
interrupt dispatching code (at CRB$L_RTINTD2) determines that the Q22 bus is 
illegally configured. 


Portion of second interrupt transfer vector initialized and used if multilevel interrupt 
dispatching is enabled in a MicroVAX 3600-series system or MicroVAX Il system. 
See Figure A—7 and Table A-—6 for a description of the contents of the interrupt 
transfer vector. 


Second interrupt transfer vector for devices with multiple interrupt vectors. The 
data structure definition macro $CRBDEF supplies symbolic offsets for only the 
first two interrupt transfer vector structures. 


VMS creates the appropriate number of interrupt transfer vector structures (as 
shown in Figure A—7) within a CRB if a driver specifies that the addresses of 
additional interrupt service routines be loaded into these structures. For example: 


DPT_STORE, CRB, CRB$L_INTD2+VEC$L_ISR,D,isr_for_vec2 
DPT_STORE, CRB, CRB$L_INTD+ (2*VEC$K_LENGTH) +VEC$L_ISR,D,isr_for_vec3 


The offset of the nth vector located within the CRB is equal to the result of the 
following formula: 


CRB$L _INTD+( n* VEC$K_LENGTH) 
VMS automatically initializes the interrupt dispatching instructions and the data 
structure locations from information located in the primary vector. The number 


of device vectors and vector structures actually created can be overridden by the 
value specified in the /NUMVEC qualifier to the SYSGEN command CONNECT. 
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| VEC$L_ISR 


Figure A—7_ Interrupt Transfer Vector Block (VEC) 
VEC$L_RTINTD* (12 bytes) 8 


VECS$L_INTD* 
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Table A-6 Interrupt Dispatch Vector Block (VEC) 


Field Name 


Contents 





VEC$L_BUGCHECK* 


VECS$L_RTINTD« 


VECS$L_INTD* 
VECS$L_ISR 
VEC$L_IDB* 


VECS$L_INITIAL 


Bugcheck data used to issue an ILLQBUSCFG bugcheck when the multilevel 
interrupt dispatching code determines that the Q22 bus is illegally configured. 


Portion of interrupt transfer vector created at system initialization when a 
MicroVAX 3600-series system or MicroVAX II system implements multilevel 
device interrupt dispatching. The code stored in this 12-byte field implements a 
conditional lowering to device IPL, as follows: 


CMPZV #PSL$V_IPL, #PSL$S_IPL, - 
A(SP), S*#DIPL 

BGEQ BUGCHECK 

SETIPL S“#DIPL 


Interrupt dispatching code, written by the driver-loading procedure as follows: 


PUSHR #°M<RO,R1,R2,R3,R4,R5> 
JSB Q# 


The destination of the JSB instruction is the driver’s interrupt service routine, as 
indicated at offset VEC$L_ISR. Under normal operations, direct-vector UNIBUS 
or Q22 bus adapters—as well as VAXBI system interrupt dispatching—transfer 
control to CRB$L_INTD. The code located here causes the processor to execute 
the PUSHR instruction to save RO through R5 on the stack and execute a JSB 
instruction to transfer control to the driver's interrupt service routine. 


In dispatching interrupts from non-direct-vector UNIBUS adapters, the UNIBUS 
adapter interrupt service routine transfers control to CRB$L_INTD+2, which 
contains the JSB instruction to the driver's interrupt service routine. Because 
the UNIBUS adapter's interrupt service routine has already saved RO through R5, 
interrupt dispatching bypasses the PUSHR instruction in these instances. 


This field, plus VEC$L_ISR, is also known as VEC$Q_DISPATCH. 


The DPT in every driver for an interrupting device specifies the address of a driver 
interrupt service routine. 


Address of IDB for controller. The driver-loading procedure creates an IDB for 
each CRB and loads the address of the IDB in this field. Device drivers use the 
IDB address to obtain the virtual addresses of device registers. 


When a driver's interrupt service routine gains control, the top of the stack 
contains a pointer to this field. 


Address of controller initialization routine. If a device controller requires 
initialization at driver-loading time and during recovery from a power failure, 
the driver specifies a value for this field in the DPT. 


The driver-loading procedure calls this routine each time the procedure loads 
the driver. The VMS power failure recovery procedure also calls this routine to 
initialize a controller after a power failure. 
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Table A—6 (Cont.) 
Field Name 
VEC$W_MAPREG 


VEC$B_NUMREG 


VEC$B_DATAPATH 


VEC$L_ADP* 


VEC$L_UNITINIT* 


A-24 


Interrupt Dispatch Vector Block (VEC) 


Contents 
The following bits are defined within VEC$W_MAPREG: 
VEC$V_MAPREG Number of first standard map register allocated to the 


driver that owns controller data channel. 


IOCSREQMAPREG writes this field when the routine 
allocates a set of standard map registers to a driver fork 
process for a DMA transfer. IOC6RELMAPREG reads the 
field to deallocate a set of map registers. 


Device drivers read this field in calculating the starting 
address of a UNIBUS or MicroVAX 
3600-series/MicroVAX Il Q22 bus transfer. 


VEC$V_MAPLOCK Map register set is permanently allocated (when set). 


Number of UNIBUS adapter or MicroVAX Q22 bus standard map registers 
allocated to driver. IOCSREQMAPREG writes this 15-bit field when the routine 
allocates a set of standard map registers. |OCS6RELMAPREG reads this field to 
deallocate a set of standard map registers. 


Data path specifier. The bits that make up this field are used as follows: 

VEC$V_DATAPATH Number of data path used in DMA transfer. The routine 
lIOCSREQDATAP writes this 5-bit field when a buffered 
data path is allocated and clears the field when the data 
path is released. 


The routine IOCSLOADUBAMAP copies the contents 

of this field into UNIBUS adapter map registers. These 
bits also serve as implicit input to the IOC6PURGDATAP 
routine. 


VEC$V_LWAE Longword access enable (LWAE) bit. Drivers set 
this bit when they wish to limit the data path to 
longword-aligned, random-access mode. The routine 
IOC$LOADUBAMAP copies the value in this field to the 
UNIBUS adapter map registers. 


<6> Reserved to DIGITAL. 


VEC$V_PATHLOCK Buffered data path allocation indicator. Drivers set this 
bit to specify that the buffered data path is permanently 
allocated. 


Address of ADP. The SYSGEN command CONNECT must specify the nexus 
number of the UNIBUS adapter used by a controller. The driver-loading procedure 
writes the address of the ADP for the specified UBA into the VEC$L_ADP field. 


IOCSREQMAPREG, !IOC$REQALTMAP, and IOC$RELMAPREG read and write fields 
in the ADP to allocate and deallocate map registers. 


Address of device driver's unit initialization routine. If a device unit requires 
initialization at driver-loading time and during recovery from a power failure, the 
driver specifies a value for this field in the DPT. The driver-loading procedure calls 
this routine for each device unit each time the procedure loads the driver. The 
VMS power failure recovery procedure also calls this routine to initialize device 
units after a power failure. 


MASSBUS drivers that support mixed device types must not use this field. 
Instead, they should specify the unit initialization routine in the unit initialization 
field of the DDT (DDT$L_UNITINIT). Other drivers can use either field. 


Table A—6 (Cont.) 
Field Name 


VEC$L_START* 
VEC$L_UNITDISC* 
VEC$W_MAPALT 


VEC$W_NUMALT 
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Interrupt Dispatch Vector Block (VEC) 


Contents 


Address of VMS start protocol routine. Use of this field is reserved to DIGITAL. 
Address of unit disconnect routine. Use of this field is reserved to DIGITAL. 


The following bits are defined within VEC$W_MAPALT: 


VEC$V_MAPALT Number of first Q22 bus alternate map register allocated 
to driver that owns controller data channel. 


lIOCS6REQALTMAP writes this field when the routine 
allocates a set of Q22 bus alternate map registers 
to a driver fork process for a DMA transfer. 
IOCSRELMAPREG reads the field to deallocate a set 
of map registers. 
Device drivers read this 15-bit field in calculating the 
starting address of a MicroVAX 3600-series/MicroVAX 
Il Q22 bus transfer that uses a set of alternate map 
registers. 

VEC$V_ALTLOCK Alternate map register set is permanently allocated 
(when set). 


Number of Q22 bus alternate map registers allocated to driver. IOCSREQALTMAP 
writes this field when allocating a set of alternate map registers. 
IOCSRELMAPREG reads this field to deallocate a set of alternate map registers. 





A.6 Device Data Block (DDB) 


The device data block (DDB) is a block that identifies the generic 
device/controller name and driver name for a set of devices attached to 

a single controller. The driver-loading procedure creates a DDB for each 
controller during autoconfiguration at system startup, and dynamically creates 
additional DDBs for new controllers as they are added to the system using 
the SYSGEN command CONNECT. The procedure initializes all fields in the 
DDB. All the DDBs in the I/O database are linked in a singly linked list. The 
contents of IOC$GL_DEVLIST point to the first entry in the list. 


VMS routines and device drivers refer to the DDB. 


The device data block is illustrated in Figure A-8 and described in 
Table A-7. 
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Figure A-8 Device Data Block (DDB) 
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Table A—7 Contents of Device Data Block 


Field Name 


DDB$L_LINK* 
DDB$L_UCB* 
DDBSW_SIZE* 
DDB$B_TYPE* 


DDB$L_DDT 


DDBS$L_ACPD 


DDBST_NAME* 


DDB$T_DRVNAME* 


DDB$L_SB* 
DDB$L_CONLINK* 
DDB$L_ALLOCLS* 
DDB$L_2P_UCB* 


Contents 


Address of next DDB. A zero indicates that this is the last DDB in the DDB chain. 
Address of UCB for first unit attached to controller. 
Size of DDB. 


Type of data structure. The driver-loading procedure writes the constant DYN$C__ 
DDB into this field when the procedure creates the DDB. 


Address of DDT. VMS can transfer control to a device driver only through 
addresses listed in the DDT, the CRB, and the UCB fork block. The DPT of every 
device driver must specify a value for this field. 


Name of default ACP (or XQP) for controller. ACPs that control access to file- 
structured devices (or the XQP) use the high-order byte of this field, DDB$B_ 
ACPCLASS, to indicate the class of the file-structured device. If the ACP_ 
MULTIPLE system parameter is set, the initialization procedure creates a unique 
ACP for each class of file-structured device. 


Drivers initialize DDB$B_ACPCLASS by invoking a DPT_STORE macro. Values for 
DDB$B_ACPCLASS are as follows: 


DDB$K __PACK Standard disk pack 

DDB$K __CART Cartridge disk pack 

DDB$K_SLOW Floppy disk 

DDB$K _TAPE Magnetic tape that simulates file-structured device 


Generic name for the devices attached to controller. The first byte of this field is 
the number of characters in the generic name. The remainder of the field consists 
of a string of up to 15 characters that, suffixed by a device unit number, identifies 
devices on the controller. 


Name of device driver for controller. The first byte of this field is the number of 
characters in the driver name. The remainder of the field contains a string of up 
to 15 characters taken from the DPT in the driver. 


Address of system block. 
Address of next DDB in the connection subchain. 
Allocation class of device. 


Address of the first UCB on the secondary path. Another name for this field is 
DDB$L_DP_UCB. 





Driver Dispatch Table (DDT) 


Each device driver contains a driver dispatch table (DDT). The DDT lists entry 
points in the driver that VMS routines call: for instance, the entry point for 
the driver start-I/O routine. 


A device driver creates a DDT by invoking the VMS macro DDTAB. The 
fields in the driver dispatch table are illustrated in Figure A~9 and described 
in Table A-8. 


A-27 


Data Structures 
A.7 Driver Dispatch Table (DDT) 


Figure A-9 Driver Dispatch Table (DDT) 
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Table A—8 Contents of Driver Dispatch Table 


Field Name 


DDT$L_START 


DDT$L_UNSOLINT 


DDT$L_FDT 


DDT$L_CANCEL 


DDT$L__REGDUMP 


DDT$W_DIAGBUF 


DDT$W_ERRORBUF 


DDTS$L_UNITINIT 


DDT$L_ALTSTART 


Contents 


Entry point to the driver’s start-|/O routine. Every driver must specify this 
address in the start argument to the DDTAB macro. 


When a device unit is idle and an I/O request is pending for that unit, 
IOCSINITIATE transfers control to the address contained in this field. 


Entry point to a MASSBUS driver’s unsolicited-interrupt service routine. The 
driver specifies this address in the unsolic argument to the DDTAB macro. 


This field contains the address of a routine that analyzes unexpected interrupts 
from a device. The standard interrupt service routine, the address of which 

is stored in the CRB, determines whether an interrupt was solicited by a 
driver. If the interrupt is unsolicited, the interrupt service routine can call the 
unsolicited-interrupt service routine. 


Address of the driver's FDT. Every driver must specify this address in the 
functb argument to the DDTAB macro. 


EXE$QIO refers to the FDT to validate 1/O function codes, decide which 
functions are buffered, and call FDT routines associated with function codes. 


Entry point to the driver's cancel-l/O routine. The driver specifies this address in 
the cancel argument to the DDTAB macro. 


Some devices require special cleanup processing when a process or a VMS 
routine cancels an I/O request before the I/O operation completes or when the 
last channel is deassigned. The $DASSGN, $DALLOC, and $CANCEL system 
services cancel |/O requests. 


Entry point to the driver's register dumping routine. The driver specifies this 
address in the regdmp argument to the DDTAB macro. 


IOC$DIAGBUFILL, ERLSDEVICERR, and ERLSDEVICTMO call the address 
contained in this field to write device register contents into a diagnostic buffer 
or error message buffer. 


Size of diagnostic buffer. The driver specifies this value in the diagbf argument 
to the DDTAB macro. The value is the size in bytes of a diagnostic buffer for 
the device. 


When EXES$OIO preprocesses an |/O request, it allocates a system buffer of the 
size recorded in this field (if it contains a nonzero value) if the process requesting 
the 1/O has DIAGNOSE privilege and specifies a diagnostic buffer in the 1/O 
request. IOC$DIAGBUFILL fills the buffer after the 1/O operation completes. 


Size of error message buffer. Tie driver specifies this value in the erlgbf 
argument to the DDTAB macro. The value is the size in bytes of an error 
message buffer for the device. 


If error logging is enabled and an error occurs during an |/O operation, the driver 
calls ERLSDEVICERR or ERLSDEVICTMO to allocate and write error-logging data 
into the error message buffer. IOCSINITIATE and IOC6REQCOM write values 
into the buffer if an error has occurred. 


Address of the device's unit initialization routine, if one exists. Drivers for | 
MASSBUS devices use this field rather than CRB$L_INTD+VEC$L_UNITINIT. 
Drivers for UNIBUS, VAXBI, and Q22 devices can use either field. 


Address of a driver's alternate start-|/O routine. EXESALTQUEPKT transfers 
control to the alternate start-l/O routine at this address. 
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Table A—8 (Cont.) Contents of Driver Dispatch Table 


Field Name 
DDT$L_MNTVER 


DDT$L_CLONEDUCB 
DDT$W_FDTSIZE* 


DDT$L_MNTV_SSSC* 
DDT$L_MNTV_FOR* 
DDT$L__MNTV_SQD+ 
DDT$L_AUX — 


STORAGE* 
DDT$L_AUX _ROUTINE* 


Contents 


‘Address of the VMS routine (IOC$MNTVER) called at the beginning and end 
of mount verification operation. The mntver argument to the DPTAB macro 
defaults to this routine. Use of the mntver argument to call any routine other 
than IOCSMNTVER is reserved to DIGITAL. 


Address of routine to call when UCB is cloned. 


Number of bytes in FDT. The driver-loading procedure uses this field to relocate 
addresses in the FDT to system virtual addresses. 


Address of routine to call when performing mount verification for a shadow-set 
state change. Use of this field is reserved to DIGITAL. 


Address of routine to call when performing mount verification for a foreign 
device. Use of this field is reserved to DIGITAL. 


Address of routine to call when performing mount verification for a sequential 
device. Use of this field is reserved to DIGITAL. 


Address of auxiliary storage area. Use of this field is reserved to DIGITAL. 


Address of auxiliary routine. Use of this field is reserved to DIGITAL. 


Driver Prologue Table (DPT) 
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When loading a device driver and its database into virtual memory, the 
driver-loading procedure finds the basic description of the driver and its 
device in a driver prologue table (DPT). The DPT provides the length, name, 
adapter type, and loading and reloading specifications for the driver. 


A device driver creates a DPT by invoking the VMS macros DPTAB and 
DPT_STORE. The driver prologue table is illustrated in Figure A-10 and 
described in Table A-9. 
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Figure A-—10 Driver Prologue Table (DPT) 
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Table A-9 Contents of Driver Prologue Table 


Field Name 


DPT$L__FLINK*« 


DPT$L_BLINK* 
DPT$W_SIZE 


DPT$B_TYPE* 


DPT$B_REFC* 


DPT$B_ADPTYPE 


DPT$W-_UCBSIZE 


DPT$L_FLAGS 
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Contents 


Forward link to next DPT. The driver-loading procedure writes this field. The 
procedure links all DPTs in the system in a doubly linked list. 


Backward link to previous DPT. The driver-loading procedure writes this field. 


Size in bytes of the driver. The DPTAB macro writes this field by subtracting 
the address of the beginning of the DPT from the address specified as the end 
argument to the DPTAB macro. The driver-loading procedure uses this value to 
determine the space needed in nonpaged system memory to load the driver. 


Type of data structure. The DPTAB macro always writes the symbolic constant 
DYN$C_DPT into this field. 


Number of DDBs that refer to the driver. The driver-loading procedure 
increments the value in this field each time the procedure creates another 
DDB that points to the driver’s DDT. 


Type of adapter used by the devices using this driver. Every driver must specify 
the string “UBA”, “MBA”, “GENBI", “NULL”, or “DR” as the value of the adapter 
argument to the DPTAB macro. Q22 bus drivers should specify “UBA” as the 
adapter type. The macro writes the value AT$_UBA, AT$_MBA, or AT$_ 
GENBI in this field. 


Size in bytes of the unit control block for a device that uses this driver. Every 
driver must specify a value for this field in the ucbsize argument to the DPTAB 
macro. 


The driver-loading procedure allocates blocks of nonpaged system memory of 
the specified size when creating UCBs for devices associated with the driver. 


Driver-loading flags. The driver can specify any of a set of flags as the value of 
the flags argument to the DPTAB macro. The driver-loading procedure modifies 
its loading and reloading algorithm based on the settings of these flags. 


Flags defined in the flag field include the following: 


DPT$V_SUBCNTRL Device is a subcontroller. 

DPT$V_SVP Device requires permanent system page to be 
allocated during driver loading. . 

DPT$V_NOUNLOAD Driver cannot be reloaded. 

DPT$V_SCS SCS code must be loaded with this driver. 

DPT$V_DUSHADOW Driver is the shadowing disk class driver. 

DPT$V_SCSCI Common SCS/CI subroutines must be loaded with 
this driver. 

DPT$V_BVPSUBS Common BVP subroutines must be loaded with this 
driver. 

DPT$V_UCODE Driver has an associated microcode image. 

DPT$V_SMPMOD Driver has been designed to run in a VMS 


multiprocessing environment. 
DPT$V_DECW_DECODE Driver is a decoding driver. 
This field is also known as DPT$B_FLAGS. 
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Table A—9 (Cont.) Contents of Driver Prologue Table 


Field Name 


DPTSW_INITTAB 


DPT$W-_REINITTAB 


DPT$W_UNLOAD 


DPT$W_MAXUNITS 


DPTSW_VERSION* 


DPT$W_DEFUNITS 


DPT$W_DELIVER 


‘DPT$W_VECTOR 


DPT$T_NAME 


DPT$Q_LINKTIME* 
DPT$L_ECOLEVEL* 
DPT$L_UCODE* 


Contents 


Offset to driver initialization table. Every driver must specify a list of data 
structure fields and values to be written into the fields at the time that the 
driver-loading procedure creates the driver’s data structures and loads the 
driver. 


The driver invokes the VMS macro DPT_STORE to specify these fields and their 
values. 


Offset to driver-reinitialization table. Every driver must specify a list of data 
structure fields and values to be written into these fields at the time that the 
driver-loading procedure creates the driver's data structures and loads the driver 
or the driver is reloaded. 


The driver invokes the VMS macro DPT_STORE to specify these fields and their 
values. 


Relative address of driver routine to be called when driver is reloaded. The 
driver specifies this field with the value of the unload argument to the DPTAB 
macro. The driver-loading procedure calls the driver unloading routine before 
reinitializing all device units associated with the driver. 


Maximum number of units on controller that this driver supports. Specify this 


value in the maxunits argument to the DPTAB macro. If no value is specified, 


the default is eight units. 


Version number that identifies format of DPT. The DPTAB macro automatically 
inserts a value in this field. SYSGEN checks its copy of the version number 
against the value stored in this field. If the values do not match, an error is 
generated. To correct the error, reassemble and relink the driver. 


Number of UCBs that the VMS autoconfiguration facility will automatically create. 
Drivers specify this number with the defunits argument to the DPTAB macro. If 
the driver also gives a value to DPT$W_DELIVER, this field is also the number 
of times that the autoconfiguration facility calls the unit delivery routine. 


Relative address of the unit delivery routine that autoconfiguration facility calls 
for the number of UCBs specified in DPT$W_DEFUNITS. The driver supplies 
the address of the unit delivery routine in the deliver argument to the DPTAB 
macro. 


Relative address of a driver-specific vector. A terminal class or port driver 
stores the address of its class or port entry vector table in this field. 


Name of the device driver. Field is 12 bytes. One byte records the length of the 
name string; the name string can be up to 11 characters. Drivers specify this 
field as the value of the name argument to the DPTAB macro. 


The driver-loading procedure compares the name of a driver to be loaded with 
the values in this field in all DPTs already loaded into system memory to ensure 
that it loads only one copy of a driver at a time. 


Time and date at which driver was linked, taken from its image header. 
ECO level of driver, taken from its image header. 


Address of associated microcode image, if DPT$V_UCODE is set in DPT$L_ 
FLAGS. Use of this field is reserved to DIGITAL. 
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Table A—9 (Cont.) Contents of Driver Prologue Table 


Field Name 


DPT$Q_LMF_1* 


DPT$W_DECW_ 
SNAME* 





Contents 


First of eight quadwords reserved to DIGITAL for the use of the VMS license 
management facility. (The others are DPT$Q_LMF_2, DPT$Q_LMF_3, DPT$O_ 
LMF_4, DPT$Q_LMF_5, DPT$Q_LMF_6, DPT$Q_LMF_7, and DPT$Q_LMF_ 
8.) 


Offset to counted ASCII string used by decoding drivers. 


Interrupt Dispatch Block (IDB) 
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The interrupt dispatch block (IDB) records controller characteristics. The 
driver-loading procedure creates and initializes this block when the procedure 
creates a CRB. The IDB points to the physical controller by storing the virtual 
address of the CSR. The CSR is the indirect pointer to all device unit registers. 


The interrupt dispatch block is illustrated in Figure A-11 and described in 
Table A-10. 


Figure A—11_ Interrupt Dispatch Block (IDB) 
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Table A-10 Contents of Interrupt Dispatch Block 


Field Name 


IDB$L__CSR* 


IDBSL__OWNER 


IDB$W_SIZE* 


IDB$B_TYPE« 


IDB$B_VECTOR* 


IDB$W_UNITS* 


IDB$B_TT_ENABLE* 
IDB$B_COMBO_CSR* 


IDB$B_COMBO_VEC* 


IDB$B_FLAGS* 


IDB$L_SPL* 


IDB$L__ADP* 


Contents 


Address of CSR. The SYSGEN command CONNECT specifies the address of a 

device’s CSR. The driver-loading procedure writes the system virtual equivalent of 
this address into the IDB$L_CSR field. Device drivers set and clear bits in device 
registers by referencing all device registers at fixed offsets from the CSR address. 


The driver-loading procedure tests the value of this field. If the value is not a CSR 
address, it sets IDB$V_NO_CSR in IDB$L_FLAGS and places the device offline by 
clearing UCB$V_ONLINE in UCB$L_STS. In this event, it does not call the driver's 
controller and unit initialization routines. 


Address of UCB of device that owns controller data channel. IOCSREQx CHANy 
writes a UCB address into this field when the routine allocates a controller data 
channel to a driver. IOCSRELx CHAN confirms that the proper driver fork process 
is releasing a channel by comparing the driver's UCB with the UCB stored in 

the IDB$L__OWNER field. If the UCB addresses are the same, IOC$RELx CHAN 
allocates the channel to a waiting driver by writing a new UCB address into the 
field. If no driver fork processes are waiting for the channel, IOCSRELxCHAN 
clears the field. 


If the controller is a single-unit controller, the unit or controller initialization routine 
should write the UCB address of the single device into this field. 


Size of IDB. The driver-loading procedure writes the constant IDB$K_LENGTH into 
this field when the procedure creates the IDB. 


Type of data structure. The driver-loading procedure writes the symbolic constant 
DYN$C_IDB into this field when the procedure creates the IDB. 


Interrupt vector number of the device, right-shifted by two bits. SYSGEN writes 
a value into this field using either the autoconfiguration database or the value 
specified in the /VECTOR qualifier to the CONNECT command. Drivers for devices 
that define the interrupt vector address through a device register must use this 
field to load that register during unit initialization and reinitialization after a power 
failure. 


Maximum number of units connected to the controller. The maximum number of 
units is specified in the DPT and can be overridden at driver-loading time. 


Reserved for use by the VMS terminal driver. 


Address of the start of CSRs for a multicontroller device such as the DMF32. 
(The name of this field is IDB$B_COMBO_CSR_OFFSET.) 


Address of the start of interrupt vectors for a multicontroller device. (The name 
of this field is IDB$B_COMBO_VECTOR_OFFSET.) 


Flags associated with the IDB. The only flag currently defined is IDB$V_NO_CSR. 
The driver loading procedure sets this flag if IDB$L__CSR does not contain the 
address of a CSR. 


Address of the device lock that—in a VMS multiprocessing environment— 
synchronizes access to device registers and those fields in the UCB accessed at 
device IPL. 


Address of the adapter’s ADP. The SYSGEN CONNECT command must specify 
the nexus number of the I/O adapter used by a device. The driver-loading 
procedure writes the address of the ADP for the specified |/O adapter into the 
IDB$L_ADP field. 
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Table A—10 (Cont.) Contents of Interrupt Dispatch Block 


Field Name 


IDB$L__UCBLST* 


Contents 


List of UCB addresses. The size of this field is the maximum number of units 
supported by the controller, as defined in the DPT. The maximum specified in the 
DPT can be overridden at driver load time. The driver-loading procedure writes a 
UCB address into this field every time the routine creates a new UCB associated 
with the controller. 





[/O Request Packet (IRP) 


When a user process queues a valid I/O request by issuing a $QIO or $QIOW 
system service, the service creates an I/O request packet (IRP). The IRP 
contains a description of the request and receives the status of the I/O 
processing as it proceeds. 


The I/O request packet is illustrated in Figure A-12 and described in 

Table A-11. Note that the standard IRP contains space for fields required 
by VMS multiprocessing and the VMS class drivers. Under no circumstances 
should a non-DIGITAL-supplied driver use these fields. 
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Figure A-12 1/O Request Packet (IRP) 
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Table A-—11 Contents of an I/O Request Packet 


Field Name 


Contents 





IRP$L_IOQFL 


IRP$L_IOQBL 
IRP$W_SIZE* 
IRP$B_TYPE* 


IRP$B_RMOD« 


IRP$L_PID* 


IRP$L_AST* 


IRP$L_ASTPRM* 


IRP$L_WIND* 


IRP$SL__UCB* 


IRP$W_FUNC 
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1/O queue forward link. EXESINSERTIRP reads and writes this field when the 
routine inserts IRPs into a pending-I/O queue. IOC6REQCOM reads and writes this 
field when the routine dequeues IRPs from a pending-I/O queue in order to send 
an IRP to a device driver. 


1/O queue backward link. EXESINSERTIRP and lOC$REQCOM read and write these 
fields. 


Size of IRP. EXESQIO writes the symbolic constant IRP$C_LENGTH into this field 
when the routine allocates and fills an IRP. 


Type of data structure. EXE$QIO writes the symbolic constant DYN$C_IRP into 
this field when the routine allocates and fills an IRP. 


Information used by |/O postprocessing. This field contains the same bit fields 
as the ACB$B_RMOD field of an AST control block. For instance, the two bits 
defined at ACB$V_MODE indicate the access mode of the process at time of 
the I/O request. EXE$QIO obtains the processor access mode from the PSL and 
writes the value into this field. 


Process identification of the process thai issued the I/O request. EXESQIO 
obtains the process identification from the PCB and writes the value into this field. 


Address of AST routine, if specified by the process in the I/O request. (This field 
is otherwise clear.) If the process specifies an AST routine address in the $QI0 
call, EXE$QIO writes the address in this field. 


During |/O postprocessing, the special kernel-mode AST routine queues a user 
mode AST to the requesting process if this field contains the address of an AST 
routine. . 


Parameter sent as an argument to the AST routine specified by the user in the 
1/O request. If the process specifies an AST routine and a parameter to that AST 
routine in the $QlO call, EXESOIO writes the parameter in this field. 


During |/O postprocessing, the special kernel-mode AST routine queues a user 
mode AST if the IRP$L_AST field contains an address, and passes the value in 
IRP$L_ASTPRM to the AST routine as an argument. 


Address of window control block (WCB) that describes the file being accessed 
in the I/O request. EXE$QIO writes this field if the 1/O request refers to a 
file-structured device. An ACP or XOP reads this field. 


When a process gains access to a file on a file-structured device or creates a 
logical link between a file and a process I/O channel, the device ACP. or-XOP 
creates a WCB that describes the virtual-to-logical mapping of the file data on the 
disk. EXE$QIO stores the address of this WCB in the IRP$L_WIND field. 


Address of UCB for the device assigned to the process’s I/O channel. EXE$QIO 
copies this value from the CCB. 


1/O function code that identifies the function to be performed for the I/O request. 
The 1/O request call specifies an 1/O function code; EXE$QIO and driver FDT 
routines map the code value to its most basic level (virtual — logical — physical) 
and copy the reduced value into this field. 


Based on this function code, EXE$QIO calls FDT action routines to preprocess 
an |/O request. Six bits of the function code describe the basic function. The 
remaining 10 bits modify the function. 


Table A—11 (Cont.) 


Field Name 


IRP$B_EFN* 


IRP$B_PRI* 


IRP$L_IOSB* 


IRP$W_CHAN+ 
IRP$W_STS 


Data Structures 
A.10 1/O Request Packet (IRP) 


Contents of an I/O Request Packet 


Contents 


Event flag number and group specified in 1/O request. If the I/O request call 
does not specify an event flag number, EXE$QIO uses event flag O by default. 
EXES$OIO writes this field. The |/O postprocessing routine calls SCHSPOSTEF to 
set this event flag when the I/O operation is complete. 


Base priority of the process that issued the I/O request. EXE$QIO obtains a value 
for this field from the process's PCB. EXESINSERTIRP reads this field to insert an 
IRP into a priority-ordered pending-|/O queue. 


Virtual address of the process's I/O status block (IOSB) that receives final status 

of the I/O request at |/O completion. EXE$QIO writes a value into this field if the 
1/O request call specifies an IOSB address. (This field is otherwise clear.) The — 

1/O postprocessing special kernel-mode AST routine writes two longwords of |/O 
status into the IOSB after the !/O operation is complete. 


When an FDT routine aborts an 1/O request by calling EXESABORTIO, 
EXE$ABORTIO fills the IRP$L_IOSB field with zeros so that |/O postprocessing 
does not write status into the IOSB. 


Index number of process |/O channel for request. EXE$QIO writes this field. 


Status of 1/O request. EXE$OIO initializes this field to O. EXE$QIO, FDT routines, 
and driver fork processes modify this field according to the current status of 

the |/O request. |/O postprocessing reads this field to determine what sort of 
postprocessing is necessary (for example, deallocate system buffers and adjust 


quota usage). 


Bits in the IRP$W_STS field describe the type of I/O function, as follows: 


IRP$V_BUFIO Buffered-1/O function 
IRP$V_FUNC Read function 
IRP$V_PAGIO Paging-|/O function 


IRP$V_COMPLX 
IRP$V_VIRTUAL 
IRP$V_CHAINED 


Complex-buffered-I/O function 
Virtual-1/O function 
Chained-buffered-|/O function 


IRP$V_SW APIO Swapping-!/O function 

IRP$V_DIAGBUF Diagnostic buffer is present 

IRP$V_PHYSIO Physical-I/O function 

IRP$V_TERMIO Terminal !/O (for priority increment calculation) 
IRP$V_MBXIO Mailbox-1/O function 

IRP$V_EXTEND An extended IRP is linked to this IRP 
IRP$V_FILACP File ACP I/O 

IRP$V_MVIRP Mount-verification 1/O function 

IRP$V_SRVIO Server-type I/O 

IRP$V_KEY Encrypted function (encryption key address at 


IRP$L__KEYDESC) 


A-39 


Data Structures 
A.10 I/O Request Packet (IRP) 


Table A—11 (Cont.) Contents of an I/O Request Packet 


Field Name 


IRP$L_SVAPTE 


_ IRP$W_BOFF 


IRP$L_BCNT 


IRP$6W_STS2 


IRP$L_IOST 1 
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Contents 


For a direct-l/O transfer, virtual address of the first page-table entry (PTE) of the 
1/O-transfer buffer, written here by the FDT routine locking process pages; for 
buffered-I/O transfer, address of a buffer in system address space, written here 
by the FDT routine allocating buffer. . 
IOC$INITIATE copies this field into UCB$L_SVAPTE before transferring control to 
a device driver start-I/O routine. 

|/O postprocessing uses this field to deallocate the system buffer for a buffered- 
1/O transfer or to unlock pages locked for a direct-I/O transfer. - 

Byte offset into the first page of a direct-|/O transfer. FDT routines calculate this 
offset and write the field. 

For buffered-I/O transfers, FDT routines must write the number of bytes to be 
charged to the process in this field because these bytes are being used for a 
system buffer. 

IOC$INITIATE copies this field into UCB$W-_BOFF before calling a device driver 
start-I/O routine. 

1/O postprocessing uses IRP$W_BOFF in conjunction with IRP$L_BCNT and 
IRP$L_SVAPTE to unlock pages locked for direct I/O. For buffered |/O, 1/O 
postprocessing adds the value of IRP$W_BOFF to the process byte count quota. 
Byte count of the I/O transfer. FDT routines calculate the count value and write 
the field. IOCSINITIATE copies the low-order word of this field into UCB$W_ 
BCNT before calling a device driver's start-1/O routine. 

For a buffered-I/O-read function, |/O postprocessing uses IRP$L_BCNT to 
determine how many bytes of data to write to the user's buffer. 

The field IRP$W_BCNT points to the low-order word of this field to provide 
compatibility with previous versions of VMS. 

Second word of |/O request status. EXE$QIO initializes this field to O. EXE$QIO, 
FDT routines, and driver fork processes modify this field according to the current 
status of the |/O request. 

Bits in the IRP$W_STS2 field describe the type of I/O function, as follows: 
IRP$V_START_PAST_HWM 1/O starts past file highwater mark. 


IRP$V_END_PAST_HWM 1/O ends past file highwater mark. 

IRP$V_ERASE Erase I/O function. 

IRP$V_PART_HWM Partial file highwater mark update. 

IRP$V_LCKIO Locked |I/O request, as used by DECnet direct 
1/0. 


First 1/O status longword. |OC$REQCOM and EXES$FINISHIO(C) write the contents 
of RO into this field. The I/O postprocessing routine copies the contents of this 
field into the user’s IOSB. 

EXE$ZEROPARM copies a O and EXESONEPARM copies p1 into this field. This 
field is a good place to put a $OlO request argument (p1 through p6) or a 
computed value. 


This field is also called IRP$L_MEDIA. 
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Table A—11 (Cont.) 
Field Name 


IRP$L_IOST2 


IRP$L_ABCNT 


IRP$L__OBCNT 


IRP$L__SEGVBN 


IRP$L_DIAGBUF* 


IRP$L_SEQNUM* 


IRP$L_EXTEND 


IRP$L_ARB* 


IRP$L_KEYDESC 
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Contents of an !/O Request Packet 


Contents 


Second |/O status longword. IOC$6REQCOM, EXE$FINISHIO, and EXE$FINISHIOC 
write the contents of R1 into this field. The 1/O postprocessing routine copies the 
contents of this field into the user's IOSB. 


The low byte of this field is also known as IRP$B_CARCON. IRP$B_.CARCON 
contains carriage control instructions to the driver. EXE$READ and EXESWRITE 
copy the contents of p4 of the user’s I/O request into this field. 


Accumulated bytes transferred in virtual I/O transfer. IOC$IOPOST reads and 
writes this field after a partial virtual transfer. 


The symbol IRP$W_ABCNT points to the low-order word of this field to provide 
compatibility with previous versions of VMS. 


Original transfer byte count in a virtual |/O transfer. IOCSIOPOST reads this 
field to determine whether a virtual transfer is complete, or whether another I/O 
request is necessary to transfer the remaining bytes. 


The symbol IRP$W_OBCNT points to the low-order word of this field to provide 
compatibility with previous versions of VMS. 


Virtual block number of the current segment of a virtual 1/O transfer. IOCSIOPOST 
writes this field after a partial virtual transfer. 


Address of a diagnostic buffer in system address space. If the I/O request call 
specifies a diagnostic buffer and if a diagnostic buffer length is specified in the 
DDT, and if the process has diagnostic privilege, EXE$QIO copies the buffer 
address into this field. 


EXE$QIO allocates a diagnostic buffer in system address space to be filled by 
IOC$DIAGBUFILL during !/O processing. During I/O postprocessing, the special 
kernel-mode AST routine copies diagnostic data from the system buffer into the 
process diagnostic buffer. 


1/O transaction sequence number. If an error is logged for the request, this field 
contains the universal error log sequence number. 


Address of an IRPE linked to this IRP. FDT routines write an extension address 
to this field when a device requires more context than the IRP can accommodate. 
This field is read by lOCSIOPOST. IRP$V_EXTEND in IRP$W_STS is set if this 
extension address is used. 


Address of access rights block (ARB). This block is located in the PCB and 
contains the process privilege mask and UIC, which are set up as follows: 


ARB$Q__PRIV Quadword containing process privilege mask 
SPARE$L Unused longword 
ARB$L_UIC Longword containing process VIC 


Address of encryption key. 


1/O Request Packet Extension (IRPE) 


I/O request packet extensions (IRPEs) hold additional I/O request 
information for devices that require more context than the standard IRP 

can accommodate. IRP extensions are also used when more than one buffer 
(region) must be locked into memory for a direct-I/O operation, or when a 
transfer requires a buffer that is larger than 64K. An IRPE provides space for 
two buffer regions, each with a 32-bit byte count. 
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FDT routines allocate IRPEs by calling EXE$ALLOCIRP. Driver routines link 
the IRPE to the IRP, store the IRPE’s address in IRP6L_EXTEND and set 
the bit field IRP$V_EXTEND in IRP$W_STS to show that an IRPE exists 
for the IRP. The FDT routine initializes the contents of the IRPE. Any fields 
within the extension not described in Table A—12 can store driver-dependent 
information. 


If the IRP extension specifies additional buffer regions, the FDT routine must 
use those buffer locking routines that perform coroutine calls back to the 
driver if the locking procedure fails (EXESREADLOCKR, EXESWRITELOCKR, 
and EXE$MODIFYLOCKR). If an error occurs during the locking procedure, 
the driver must unlock all previously locked regions using MMG$UNLOCK 
and deallocate the IRPE before returning to the buffer locking routine. 


IOC$IOPOST automatically unlocks the pages in region 1 (if defined) and 
region 2 (if defined) for all the IRPEs linked to the IRP undergoing completion 
processing. IOC$IOPOST also deallocates all the IRPEs. 


The I/O request packet extension is illustrated in Figure A-13 and described 
in Table A-12. 


Figure A-13 1/O Request Packet Extension (IRPE) 


00 


IRPESB_TYPE* IRPESW_SIZE* 08 


unused (31 bytes) 


IRPE$W_STS 
IRPE$L_SVAPTE1 40 
IRPE$W_BOFF 1 44 
IRPE$L_BCNT 1 48 
IRPE$L_SVAPTE2 52 


IRPE$L_BCNT2 60 


unused (16 bytes) 64 


IRPE$L__EXTEND 80 
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Table A-12 Contents of the |/O Request Packet Extension 


Field Name 
IRPE$SW_SIZE* 
IRPESB_T YPE* 
IRPESW_STS 


IRPE$L_SVAPTE1 


IRPE$ W_BOFF 1 
IRPESL__BCNT 1 
IRPESL__SVAPTE2 


IRPE$ W_BOFF2 
IRPESL__BCNT2 
IRPESL__EXTEND 


Contents 


Size of IRPE. EXESALLOCIRP writes the constant IRP$C_LENGTH to this field. 


Type of data structure. EXESALLOCIRP writes the constant DYN$C_IRP to this 
field. 


IRPE status field. If bit IRPESV_EXTENDIRPE is set, it indicates that another IRPE 
is linked to this one. 


System virtual address of the page-table entry (PTE) that maps the start of region 
1. FDT routines write this field. If the region is not defined, this field is zero. 


Byte offset of region 1. FDT routines write this field. 
Size in bytes of region 1. FDT routines write this field. 


System virtual address of the PTE that maps the start of region 2. Set by FDT 
routines. This field contains a value of zero if region 2 is not defined. 


Byte offset of region 2. This field is set by FDT routines. 
Size in bytes of region 2. FDT routines write this field. 
Address of next IRPE for this IRP, if any. 





Object Rights Block (ORB) 


The object rights block (ORB) is a data structure that describes the rights 
a process must have in order to access the object with which the ORB is 
associated. 


The ORB is usually allocated when the device is connected by means of 
SYSGEN’s CONNECT command. SYSGEN also sets the address of the ORB 
in UCB$L_ORB at that time. 


The object rights block is illustrated in Figure A~14 and described in 
Table A-13. 
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Figure A-—14 Object Rights Block (ORB) 
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Table A-13 Contents of Object Rights Block 


Field 


ORB$L_—OWNER 
ORB$L_ACL_MUTEX 


ORB$W_SIZE* 


ORB$B_TYPE* 


ORB$B_FLAGS 


ORB$W_REFCOUNT 
ORB$OQ__MODE_PROT 


ORB$L_SYS_PROT 


ORB$L_OWN_PROT 
ORB$L_.GRP_PROT 
ORB$L_WOR_PROT 
ORB$L_—ACLFL 


ORB$L_ACLBL 


ORB$R_MIN_CLASS 
ORB$R_MAX_CLASS 


Contents 


UIC of the object’s owner. 


Mutex for the object's ACL, used to control access to the ACL for reading and 

writing. The driver-loading procedure initializes this field with —1. 

Size in bytes of ORB. The driver-loading procedure writes the symbolic constant 

ORB$K_LENGTH into this field when it creates an ORB. 

Type of data structure. The driver-loading procedure writes the symbolic constant 

DYN$C_ORB into this field when it creates an ORB. 

Flags needed for interpreting portions of the ORB that can have alternate 

meanings. The following fields are defined within ORB$B_FLAGS: 

ORB$V_PROT_16 The driver-loading procedure sets this bit to 1, 
signifying SOGW protection. 


ORB$V_ACL_QUEUE This flag represents the existence of an ACL queue. 


The driver-loading procedure does not set this bit. 
ORB$V_MODE_.VECTOR 
ORB$V_NOACL 
ORB$V_CLASS_ PROT 
Reference count. 


Use vector mode protection, not byte mode. 
This object cannot have an ACL. 


Security classification is valid. 


Mode protection vector. The low byte of this quadword is known as ORB$B_ 
MODE. 


System protection field. The low word of this field is known as ORB$W_PROT 
and contains the standard SOGW protection. 


Owner protection field. 
Group protection field. 
World protection field. 


ACL queue forward link. If ORB$V_ACL_QUEUE is 0, this field should contain 
O. This field is also known as ORB$L_ACL_COUNT and is cleared by the 
driver-loading procedure. 


ACL queue backward link. If ORB$V_ACL_QUEUE is 0, this field should contain 
0. This field is also known as ORB$L_ACL_DESC and is cleared by the driver- 
loading procedure. 


Minimum classification mask. 


Maximum classification mask. 


Spin Lock Data Structure (SPL) 


The spin lock data structure records all information necessary to properly 
grant, release, and record the ownership of a spin lock. Each static system 
spin lock (including the fork locks) and device lock uses an SPL to record the 
IPL required for spin lock acquisition, its rank, and its owner. The spin lock 
structure also maintains a history of spin lock use and a variety of counters 
used in accounting and debugging. 


A-45 


Data Structures 
A.13 Spin Lock Data Structure (SPL) 


Static system spin locks are assembled from module LDAT and are located 
from a vector of longword addresses starting at SMPSAR_SPNLKVEC. 
UCB$L_DLCK contains the address of the device lock for the corresponding 
device unit. 


The fields described in the spin lock data structure are illustrated in 
Figure A-15 and described in Table A-14. 


Figure A-15 Spin Lock Data Structure (SPL) 


SPL$B_VEC_INX* SPL$B_RANK* SPL$B_IPL*« SPL$B_SPINLOCK* 
SPL$W_WAIT_CPUS* SPL$W_OWN-_CNT* 
SPL$B_SUBTYPE* SPL$B_TYPE* SPL$W_SIZE* 


SPL$L_OWN_CPU* 

















SPL$L_OWN__PC_VEC* (32 bytes) 


SPL$L_WAIT_PC* 


SPL$Q_ACQ._COUNT* 


48 
52 


SPL$L_BUSY_WAITS* 60 


SPL$Q_SPINS* 64 





SPL$L_TIMO_INT* 72 


SPL$L_RLS_PC* 76 
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Table A-—14 Contents of the Spin Lock Data Structure 


Field 
SPL$B_SPINLOCK* 


SPL$B_IPL* 
SPL$B_RANK* 


SPL$B_VEC_INX* 
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The following fields are defined within SPL$B_SPINLOCK: 

SPL$V_INTERLOCK Spin lock access interlock. When set, this bit signifies 
that the spin lock is owned. 

Fil Reserved to DIGITAL. 

IPL required for spin lock acquisition. 

Spin lock rank. Note that the internal value of a spin lock’s rank, as stored in this 

field, is the inverse of the spin lock’s logical rank, as displayed by the System 

Dump Analyzer and listed in Table 3—3. For instance, the structure of a spin lock 

with a logical rank of O contains the value 31 in this field. 


Index of the next entry to be written in the spin lock PC vector index (SPL$L_— 
OWN_PCVEC). SPL$B_VEC_INX is updated upon each successful acquisition or 
release of the spin lock. 
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Table A—14 (Cont.) Contents of the Spin Lock Data Structure 


Field 
SPL$W_OWN_CNT* 


SPL$W_WAIT_CPUS* 
SPL$W_SIZE* 
SPL$B_TYPE* 


SPLSB_SUBT YPE* 


SPL$L_OWN_CPU+ 


SPL$L_OWN_PC_ 
VEC 


SPL$L_WAIT_PC* 
SPL$Q_ACQ_COUNT* 
SPL$L_BUSY_WAITS+ 
SPL$Q_SPINS* 
SPL$L_TIMO_INT# 
SPL$L_RLS_PC* 


Contents 


Ownership count. This field is —1 if the spin lock is unowned, zero or positive if 
owned. When a processor initially acquires a spin lock, this field goes from —1 
to zero. A positive ownership count signifies concurrent acquisitions by a single 
processor. 


Number of processors waiting to obtain the spin lock. 
Size of spin lock data structure (SPL$C_LENGTH). 


Type of data structure. VMS writes the value DYN$C_SPL in this field when it 
creates the SPL data structure. 


Spin lock subtype. This field can contain the following values: 
SPL$C_SPL_SPINLOCK Static system spin lock 


SPL$C_SPL__FORKLOCK Fork lock 
SPL$C_SPL_DEVICELOCK Device lock (dynamic spin lock) 


Physical ID of owner CPU. This field is initialized to a4) Upon a successful 
acquisition, VMS copies the physical ID of the acquiring processor from CPU$L_ 
PHY_CPUID to this field. 


Last eight calling PCs of acquirers and releasers of the spin lock. SPL$B_VEC_ 
INX serves as the index of the next vector to be written in this array. 


Last busy-wait PC. 

Count of successful acquisitions. 

Count of failed acquisitions. 

Count of number of spins. 

Timeout interval before a spin lock acquisition attempt fails. 


PC of the last unconditional release of a set of nested acquisitions of the spin 
lock. 





Unit Control Block (UCB) 


The unit control block (UCB) is a variable-length block that describes a single 
device unit. Each device unit on the system has its own UCB. The UCB 
describes or provides pointers to the device type, controller, driver, device 
status, and current I/O activity. 


During autoconfiguration, the driver-loading procedure creates one UCB 

for each device unit in the system. A privileged system user can request 

the driver-loading procedure to create UCBs for additional devices with the 
SYSGEN command CONNECT, as described in Chapter 15. The procedure 
creates UCBs of the length specified in the DPT. The driver uses UCB storage 
located beyond the standard UCB fields for device-specific data and temporary 
driver storage. 


The driver-loading procedure initializes some static UCB fields when it creates 
the block. VMS and device drivers can read and modify all nonstatic fields 
of the UCB. The UCB fields that are present for all devices are illustrated in 
Figure A-17 and described in Table A-16. The length of the basic UCB is 
defined by the symbol UCB$K_LENGTH. 
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UCBs are variable in length depending on the type of device and whether the 
driver performs error logging for the device. VMS defines a number of UCB 
extensions in the data structure definition macro $UCBDEF and defines a 
terminal device extension in $TTYUCBDEF. Table A-15 lists those extensions 
that are most often used by device drivers, indicating where each is described 
in this appendix. Note that use of the dual-path extension is reserved to 
DIGITAL; its contents should remain zero. 


Table A-15 UCB Extensions and Sizes Defined in $UCBDEF 


Extension 


Base UCB 


Error log extension 


Dual-path extension 


Local tape extension 
Local disk extension 


Terminal extension! 


Used by Size Figure Table 


All devices UCBS$K_SIZE A-17 A-16 
All disk and tape devices UCBS$K_ERL_LENGTH A-18 A-17 
Reserved to DIGITAL UCB$K_DP_LENGTH = = 


(UCB$K _2P_LENGTH) 
All tape devices UCB$K_LCL__TAPE_LENGTH A-19 A-18 
All disk devices UCB$K_—LCL_DISK__LENGTH A-20 A-19 


Terminal class and port UCB$K_TT_LENGTH A-212 A-20 
drivers 


'The terminal UCB extension is defined by the data structure definition macro, $TTYUCBDEF. 


2Fields marked by asterisks indicate fields that may be written only by the VMS terminal class driver (TTDRIVER.EXE); a 
port driver may only read these fields. 
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In order to use an extended UCB, a device driver must specify its length in 
the ucbsize argument to the DPTAB macro. For instance: 


DPTAB -, 


UCBSIZE=UCB$K_LCL_TAPE_LENGTH, - 


As represented in Figure A-16, each UCB extension used in a disk or tape 
driver builds upon the base UCB structure and any extension $UCBDEF 
defines earlier in the structure. (Note that shaded UCB extensions are 
reserved to DIGITAL.) For instance, if you specify a UCB size of UCB$K_ 
LCL_TAPE_LENGTH, the size of the resulting UCB can accommodate the 


- base UCB, the error log extension, the dual-path extension, and the local tape 


extension. 


Data Structures 
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Figure A-16 Composition of Extended Unit Control Blocks 
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A device driver can further extend a UCB by using the $DEFINI, $DEF, 
$DEFEND, and —VIELD macros. For instance: 


$DEFINI UCB 
.=UCB$K_LCL_DISK_LENGTH 
$DEF UCB$W_XX_FIELD1 ~.BLKW 1 
$DEF UCB$W_XX_FIELD2 .BLKW 1 
$DEF UCB$L_XX_FLAGS .BLKL 1 
_VIELD UCB,0O,<- 
<XX_BIT1i, ,M>,- 
<XX_BIT2, ,M>,- 
> 
$DEF UCB$K_XX_LENGTH 
$DEFEND UCB 


In this case, too, the driver must ensure that it specifies the length of the 
extended UCB in the ucbsize argument of the DPTAB macro: 


DPTAB -, 


UCBSIZE=UCB$K_XX_LENGTH, - 


A-49 


Data Structures 
A.14 Unit Control Block (UCB) 


A-50 


UCB$L_DLCK* 


Figure A—17 Unit Control Block (UCB) 
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Table A-—16 Contents of Unit Control Block 


Field Name 


UCBS$L_FOFL* 


UCB$L_FOBL* 


UCB$W_SIZE* 


UCB$B_TYPE* 


UCB$B_FLCK 


Contents 


Fork queue forward link. The link points to the next entry in the fork queue. 
EXESIOFORK and VMS resource management routines write this field. The queue 
contains addresses of UCBs that contain driver fork process context of drivers 
waiting to continue I/O processing. 


Fork queue backward link. The link points to the previous entry in the fork queue. 
EXESIOFORK and VMS resource management routines write this field. 


Size of UCB. The DPT of every driver must specify a value for this field. The 
driver-loading procedure uses the value to allocate space for a UCB and stores 
the value in each UCB created. Extra space beyond the standard bytes in a UCB 
(UCB$K_LENGTH) is for device-specific data and temporary storage. 


Type of data structure. The driver-loading procedure writes the constant DYN$C_ 
UCB into this field when the procedure creates the UCB. 


Index of the fork lock that synchronizes access to this UCB at fork level. The DPT 
of every driver must specify a value for this field. The driver-loading procedure 
writes the value in the UCB when the procedure creates the UCB. All devices 
that are attached to a single I/O adapter and actively compete for shared adapter 
resources and/or a controller data channel must specify the same value for this 
field. 


When VMS creates a driver fork process to service an I/O request for a device, 
the fork process gains control at the IPL associated with the fork lock, holding the 
fork lock itself in a VMS multiprocessing environment. When the driver creates 

a fork process after an interrupt, VMS inserts the fork block into a processor- 
specific fork queue based on this fork IPL. A VMS fork dispatcher, executing 

at fork IPL, obtains the fork lock (if necessary), dequeues the fork block, and 
restores control to the suspended driver fork process. 


This field is also known as UCB$B_FIPL. Drivers designed to execute exclusively 
in a VMS uniprocessing environment store the fork IPL associated with the UCB 
in this field. 


A-51 


Data Structures 
A.14 Unit Control Block (UCB) 


Table A—16 (Cont.) Contents of Unit Control Block 


Field Name 
UCB$L_FPC 


UCB$L_FR3 


UCB$L_FR4 


UCB$W_BUFQUO+* 
UCB$W_INIQUO+ 
UCBS$L_ORB* 


UCB$L_LOCKID+ 


UCB$L __CRB* 


UCB$L_—DLCK* 


UCB$L__DDB* 


UCB$L_PID+ 


UCBS$L _LINK* 
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Fork process driver PC address. When a VMS routine saves driver fork context 
in order to suspend driver execution, the routine stores the address of the next 
driver instruction to be executed in this field. A VMS routine that reactivates a 
suspended driver transfers control to the saved PC address. 


VMS routines that suspend driver processing include EXE$IOFORK, 
IOC$REQxCHANy, IOCSREQMAPREG, IOC$REQALTMAP, IOCSREQDATAP, and 
IOCSWFIKPCH. Routines that reactivate suspended drivers include IOC6RELCHAN, 
IOCSRELMAPREG, IOC$RELALTMAP, IOC$RELDATAP, EXESFORKDSPTH, and 
driver interrupt service routines. 


When a driver interrupt service routine determines that a device is expecting an 
interrupt, the routine restores control to the saved PC address in the device’s 
UCB. 


Value of R3 at the time that a VMS routine suspends a driver fork process. The 
value of R3 is restored just before a suspended driver regains control. 


Value of R4 at the time that a VMS routine suspends a driver fork process. The 
value of R4 is restored just before a suspended driver regains control. 


Buffered-|/O quota if the UCB represents a mailbox. 
Initial buffered-I/O quota if the UCB represents a mailbox. 


Address of ORB associated with the UCB. SYSGEN places the address in this field 
when you use SYSGEN’s CONNECT command. 


Lock management lock ID of device allocation lock. A lock management lock 
is used for device allocation so that device allocation functions properly for 
cluster-accessible devices in a VAXcluster (DEV$V_CLU set within UCB$L_ 
DEVCHAR2). 


Address of primary CRB associated with the device. The driver-loading procedure 
writes this field after it creates the associated CRB. Driver fork processes read 
this field to gain access to device registers. VMS routines use UCB$L_CRB to 
locate interrupt-dispatching code and the addresses of driver unit and controller 
initialization routines. 


Address of device lock that—in a VMS multiprocessing environment— 
synchronizes access to device registers and those fields in the UCB accessed 
at device IPL. The driver-loading routine copies the address of the device lock 
in the CRB (CRB$L_DLCK) to this field as it creates a UCB for each device on a 
controller. 


Address of DDB associated with device. The driver-loading procedure writes this 
field when the procedure creates the associated UCB. VMS routines generally 
read the DDB field in order to locate device driver entry points, the address of a 
driver FDT, or the ACP associated with a given device. 


Process identification number of the process that has allocated the device. 
Written by the $ALLOC system service. 


Address of next UCB in the chain of UCBs attached to a single controller and 
associated with a DDB. The driver-loading procedure writes this field when the 
procedure adds the next UCB. Any VMS routine that examines the status of all 
devices on the system reads this field. Such routines include EXE$ TIMEOUT, 
lIOCSSEARCHDEV, and power failure recovery routines. 


Table A—16 (Cont.) 
Field Name 
UCB$L_VCB* 


UCB$L_DEVCHAR 


Contents 
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Address of volume control block (VCB) that describes the volume mounted on the 
device. This field is written by the device’s ACP and read by EXESQIOACPPKT, 
ACPs, and the XOP. 


First longword of device characteristics bits. The DPT of every driver 

should specify symbolic constant values (defined by the $DEVDEF macro in 
SYS$LIBRARY:STARLET.MLB) for this field. The driver-loading procedure writes 
the field when the procedure creates the UCB. The $QIO system service reads 
the field to determine whether a device is spooled, file structured, shared, has a 
volume mounted, and so on. 


The system defines the following device characteristics: 


DEV$V_REC 
DEV$V_CCL 
DEV$V_TRM 
DEV$\V_DIR 

DEV$V_SDI 

DEV$V_SOD 
DEV$V_SPL 

DEV$V_OPR 
DEV$V_RCT 
DEV$V_NET 
DEV$V_FOD 
DEV$V_DUA 
DEV$V_SHR 


DEV$V_GEN 
DEV$V_AVL 
DEV$V_MNT 
DEV$V_MBX 
DEV$V_DMT 
DEV$V_ELG 
DEV$V_ALL 
DEV$V_FOR 
DEV$V_SWL 
DEV$V_IDV 
DEV$V_ODV 
DEV$V_RND 
DEV$V_RTM 
DEV$V_RCK 
DEV$V_WCK 


Record-oriented device 

Carriage control device 

Terminal device 

Directory-structured device 

Single directory-structured device 

Sequential block-oriented device (magnetic tape, for example) 
Device spooled 

Operator device 

Device contains RCT 

Network device 

File-oriented device (disk and magnetic tape, for example) 
Dual-ported device . 


Shareable device (used by more than one program 
simultaneously) 


Generic device 

Device available for use 

Device mounted 

Mailbox device 

Device marked for dismount 

Error logging enabled 

Device allocated 

Device mounted as foreign (not file structured) 
Device software write-locked 
Device capable of providing input 
Device capable of providing output 
Device allowing random access 
Real-time device 

Read-checking enabled 
Write-checking enabled 
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Table A—16 (Cont.) Contents of Unit Control Block 
Field Name Contents 


UCB$L_DEVCHAR2 Second longword of device characteristics. The DPT of every driver 
should specify symbolic constant values (defined by the $DEVDEF macro in 
SYS$LIBRARY:STARLET.MLB) for this field. The driver-loading procedure writes 
the field when the procedure creates the UCB. . 


The system defines the following device characteristics: 
DEV$V_CLU Device available clusterwide 


DEV$V_DET Detached terminal 

DEV$SV_RTT Remote-terminal UCB extension 
DEV$V_CDP Dual-pathed device with two UCBs 
DEV$V_2P Two paths known to device 
DEV$V_MSCP Disk or tape accessed using MSCP 
DEV$V_SSM Shadow set member 

DEV$V_SRV Served by MSCP server 

DEV$V_RED Redirected terminal 

DEV$V_NNM Device name has a prefix of the format “node$” 
DEV$V_WBC Device supports write-back caching 
DEV$V_WTC Device supports write-through caching 
DEV$V_HOC Device supports host caching 


UCB$L_AFFINITY* Bit mask of the CPU-IDs of processors in a VMS multiprocessing system that 
have physical connectivity to the device. Such processors can thereby access the 
device's registers and initiate |/O operations on the device. 


UCB$B_DEVCLASS Device class. The DPT of every driver should specify a symbolic constant (defined 
by the $DCDEF macro) for this field. The driver-loading procedure writes this field 
when it creates the UCB. 


Drivers with set mode and device characteristics functions can rewrite the value 
in this field with data supplied in the characteristics buffer, the address of which 
is passed in the |/O request. 


VMS defines the following device classes: 


DC$_DISK Disk 
DC$_TAPE Tape 
DC$_SCOM Synchronous communications _ 
DC$_CARD Card reader 
DC$_TERM Terminal 
DC$_LP Line printer 
DC$_WORKSTATION Workstation 
DC$_REALTIME Real time 
DC$_BUS Bus 
DC$_MAILBOX Mailbox 
DC$_MISC Miscellaneous 


Note that the definition of a device as a real-time device (DC$_REALTIME) is 
somewhat subjective; it implies no special treatment by VMS. 
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Table A—16 (Cont.) 
Field Name 


UCB$B_DEVTYPE 


UCB$W_DEVBUFSIZ 


UCB$OQ_DEVDEPEND 


UCB$Q_DEVDEPND2 


UCBS$L_IOQFL* 


UCBS$L_IOQBL* 


UCBSW_UNIT* 


UCB$W_CHARGE* 
UCBS$L_IRP 


UCBSW_REFC* 
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Contents 


Device type. The DPT of every driver should specify a symbolic constant (defined 
by the $DCDEF macro) for this field. The driver-loading procedure writes the field 
when it creates the UCB. 


Drivers for devices with set mode and set characteristics functions can rewrite 
the value in this field with data supplied in the characteristics buffer, the address 
of which is passed in the |/O request. 


Default buffer size. The DPT can specify a value for this field if relevant. The 
driver-loading procedure writes the field when it creates the UCB. 


Drivers for devices with set mode and set characteristics functions can rewrite 
the value in this field with data supplied in the characteristics buffer, the address 
of which is passed in the |/O request. This field is used by RMS for record 1/O on 
nonfile devices. 


Device-descriptive data interpreted by the device driver itself. The DPT can 
specify a value for this field. The driver-loading procedure writes this field when it 
creates the UCB. 


Drivers for devices with set mode and set characteristics functions can rewrite 
the value in this field with data supplied in the characteristics buffer, the address 
of which is passed in the I/O request. 


Second longword for device-dependent status. This field is an extension of 
UCB$O_DEVDEPEND. 


Pending-!/O queue listhead forward link. The queue contains the addresses of 
IRPs waiting for processing on a device. EXESINSERTIRP inserts IRPs into the 
pending-|/O queue when a device is busy. |OCSREQCOM dequeues IRPs when 
the device is idle. 


The queue is a priority queue that has the highest priority IRPs at the front of the 
queue. Priority is determined by the base priority of the requesting process. IRPs 
with the same priority are processed first-in/first-out. 


Pending-|/O queue listhead backward link. EXESINSERTIRP and IOC$6REQCOM 
modify the pending-!/O queue. 


Number of the physical device unit; stored as a binary value. The driver-loading 
procedure writes a value into this field when it creates the UCB. Drivers for 
multiunit controllers read this field during unit initialization to identify a unit to the 
controller. 


Mailbox byte count quota charge, if the device is a mailbox. 
Address of IRP currently being processed on the device unit by the driver fork 
process. IOC$INITIATE writes the address of an IRP into this field before the 


routine creates a driver fork process to handle an |/O request. From this field, a 
driver fork process obtains the address of the IRP being processed. 


The value contained in this field is not valid if the UCB$V_BSY bit in UCB$L_STS 
is clear. 


Reference count of processes that currently have process I/O channels assigned 
to the device. The $ASSIGN and $ALLOC system services increment this field. 
The $DASSGN and $DALLOC system services decrement this field. 
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Field Name 
UCB$B_DIPL 


UCB$B_AMOD+ 


UCBSL_AMB* 


UCB$L_STS 
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Contents 


Interrupt priority level (IPL) at which the device requests hardware interrupts. 

The DPT of every driver must specify a value for this field. The driver-loading 
procedure writes this field when the procedure creates the UCB. When the driver- 
loading procedure subsequently creates the device lock’s spin lock structure 
(SPL), it moves the contents of this field into SPL$B_IPL. 


In a VMS uniprocessing environment, device drivers raise IPL to device IPL 
before reading or writing device registers or accessing other fields in the UCB 
synchronized at device IPL. In a VMS multiprocessing environment, drivers obtain 
the device lock at UCB$L_DLCK, thereby also raising IPL to device IPL in the 
process. 


Access mode at which allocation occurred, if the device is allocated. Written by 
the $ALLOC and $DALLOC system services. 


Associated mailbox UCB pointer. A spooled device uses this field for the address 
of its associated device. Devices that are nonshareable and not file oriented can 
use this field for the address of an associated mailbox. 

Device unit status (formerly UCB$W_STS). Written by drivers, IOC6REQCOM, 
lIOCS$CANCELIO, IOCSINITIATE, IOC$WFIKPCH, IOC$WFIRLCH, EXESINSIOQ, and 
EXE$TIMEOUT. This field is read by drivers, the $QIO system service routines, 
IOCSREQCOM, IOCS$INITIATE, and EXESTIMEOUT. 


This longword includes the following bits: 


UCB$V_TIM Timeout enabled. 

UCB$V_INT Interrupts expected. 

UCB$V_ERLOGIP Error log in progress. 
UCB$V_CANCEL Cancel I/O on unit. 

UCB$V_ONLINE Device is on line. 

UCB$V_POWER Power has failed while unit was busy. 
UCB$V_TIMOUT Unit is timed out. 

UCB$V_INTTYPE Receiver interrupt. 

UCB$V_BSY Unit is busy. 

UCB$V_MOUNTING Device is being mounted. 
UCB$V_DEADMO Deallocate device at dismount. 
UCB$V_VALID Volume appears valid to software. 
UCB$V_UNLOAD Unload volume at dismount. 
UCB$V_TEMPLATE Template UCB from which other UCBs for this device 


are made. The $ASSIGN system service checks this 
bit in the requested UCB and, if the bit is set, creates 
a UCB from the template. The new UCB is assigned 


instead. 
UCB$V_MNTVERIP Mount verification in progress. 
UCB$V_WRONGVOL Volume name does not match name in the VCB. 
UCB$V_DELETEUCB Delete this UCB when the value in UCB$W_REFC 


becomes zero. 
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Field Name Contents 
UCB$V_LCL VALID The volume on this device is valid on the local node. 
UCB$V_SUPMVMSG Suppress mount-verification messages if they indicate 


UCB$W_DEVSTS 


UCB$W-_OLEN* 
UCB$L_DUETIM* 


UCB$L_OPCNT* 


success. 


UCB$V_MNTVERPND Mount verification is pending on the device and the 
device is busy. 


UCB$V_DISMOUNT Dismount in progress. 

UCB$V_CLUTRAN VAXcluster state transition in progress. 
UCB$V_WRTLOCKMV Write-locked mount verification in progress. 
UCB$V_SVPN_END Last byte used from page is mapped by a system 


virtual page number. 
Device-dependent status. Read and written by device drivers. 
The system defines the following status bits: 


UCB$V_JOB Job controller has been notified. 
UCB$V_TEMPL_BSY Template UCB is busy. 

UCB$V_PRMMBX Device is a permanent mailbox. 

UCB$V_DELMBX Mailbox is marked for deletion. 

UCB$V_SHMMBS Device is shared-memory mailbox. 

Disk drivers use bits in UCB$W_DEVSTS as follows: 

UCB$V_ECC ECC correction made. 

UCB$V_DIAGBUF Diagnostic buffer is specified. 

UCB$V_NOCNVRT No logical block number to media address conversion. 
UCB$V_DX_WRITE Console floppy write operation. 


UCB$V_DATACACHE Data blocks are being cached. 
Length of pending-I/O queue (pointed to by UCB$L_IOQFL). 


Due time for |/O completion. Stored as the low-order 32-bit absolute time (time 
in seconds since the operating system was booted) at which the device will time 
out. IOCSWFIKPCH and IOCSWFIRLCH write this value when they suspend a 
driver to wait for an interrupt or timeout. 


EXESTIMEOUT examines this field in each UCB in the |/O database once per 
second. If the timeout has occurred and timeouts are enabled for the device, 
EXE$TIMEOUT calls the device driver timeout handler. 


Count of operations completed on device unit since last bootstrap of VMS 
system. IOCS6REQCOM writes this field every time the routine inserts an IRP into 
the I/O postprocessing queue. 
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Table A—16 (Cont.) Contents of Unit Control Block 


Field Name 


UCB$L_SVPN* 


UCB$L_SVAPTE 


UCBSW_BOFF 


UCBSW_BCNT 


UCBS$B_ERTCNT 


UCB$B_ERTMAX 


UCBSW_ERRCNT 


UCB$L_PDT+ 
UCB$L_DDT+ 


UCBSL_MEDIA _ID* 
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Index to the virtual address of the system PTE that the driver loading procedure 
has permanently allocated to the device. The system virtual address of the page 
described by this index can be calculated by the following formula: 


(index * 20016) + 8000000016 


If a DPT specifies DPT$M_SVP in the flags argument to the DPTAB macro, the 
driver-loading procedure allocates a page of nonpaged system memory to the 
device. The procedure writes the system PTE’s index into UCB$L_SVPN when 
the procedure creates the UCB. 


Disk drivers use this field for ECC error correction. 


For a direct-l/O transfer, the virtual address of the system PTE for the first page 
to be used in the transfer; for a buffered-I/O transfer, the virtual address. of the 
system buffer used in the transfer. 


IOCSINITIATE writes this field from IRP$L_SVAPTE before calling a driver 
start-|/O routine. Drivers read this value to compute the starting address of a 
transfer. 


For a direct-//O transfer, the byte offset in the first page of the transfer buffer; 
for a buffered-I/O transfer, the number of bytes charged to the process for the 
transfer. 


IOC$INITIATE copies this field from the IRP. Drivers read the field in calculating 
the starting address of a DMA transfer. If only part of a DMA transfer succeeds, 
the driver adjusts the value in this field to be the byte offset in the first page of 
the data that was not transferred. 


Count of bytes in the I/O transfer. IOCSINITIATE copies this field from the 
IRP. Drivers read this field to determine how many bytes to transfer in an I/O 
operation. . 


Error retry count of the current 1/O transfer. The driver sets this field to the 
maximum retry count each time it begins |/O processing. Before each retry, the 
driver decreases the value in this field. During error logging, IOC6REQCOM copies 
the value into the error message buffer. 


Maximum error retry count allowed for single 1/O transfer. The DPT of some 

drivers specifies a value for this field. The driver-loading procedure writes the 
field when the procedure creates the UCB. During error logging, IOC6REQCOM 
copies the value into the error message buffer. 


Number of errors that have occurred on the device since VMS booted. The 
driver-loading procedure initializes the field to O when the procedure creates the 
UCB. ERL$DEVICERR and ERL$DEVICTMO increment the value in the field and 
copy the value into an error message buffer. The DCL command SHOW DEVICE 
displays in its error count column the value contained in this field. 


Address of port descriptor table (PDT). This field is reserved for VMS SCS port 
drivers. 


Address of DDT for unit. The driver load procedure writes the contents of 
DDB$L_DDT for the device controller to this field when it creates the UCB. 


Bit-encoded media name and type, used by MSCP devices. 
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Figure A—18 UCB Error-Log Extension 
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Table A-17 UCB Error-Log Extension 


Field Name 


UCB$B_SLAVE* 
UCB$B_SPR 


UCB$B_FEX 


UCB$B_CEX 


UCBSL_EMB* 


UCBSW_FUNC 
UCB$L_DPC 
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Unit number of slave controller. 


Spare byte. This field is reserved for driver use. MASSBUS adapter drivers use 
this field to store a fixed offset to the MASSBUS adapter registers for the unit. 


Device-specific field. This field is reserved for driver use. Certain VMS disk 
drivers (such as DLDRIVER in Appendix E) use this field to store an index in a 
hardware function dispatch table. 


Device-specific field. This field is reserved for driver use. Certain VMS disk 
drivers (such as DLDRIVER in Appendix E) use this field to store an index into a 
software function case table. 


Address of error message buffer. If error logging is enabled and a 
device/controller error or timeout occurs, the driver calls ERLSDEVICERR or 
ERLSDEVICTMO to allocate an error message buffer and copy the buffer address 
into this field. IOCSREQCOM writes final device status, error counters, and |/O 
request status into the buffer specified by this field. 


1/O function modifiers. This field is read and written by drivers that log errors. 


Device-specific field. This field is reserved for driver use. Certain VMS disk 
drivers (such as DLDRIVER in Appendix E) use this field to store the driver's return 
PC across a dispatch to a hardware function routine. 


Figure A-19 UCB Local Tape Extension 
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Table A-18 UCB Local Tape Extension 


Field Name 


UCB$W__DIRSEO 


UCB$B_ONLCNT 


UCBS$B_PREV_RECORD 
UCB$L_RECORD 
UCB$L_TMV_RECORD 
UCBSW_TMV_CRC1 
UCBSW_TMV_CRC2 
UCB$W_TMV_CRC3 
UCBSW_TMV_CRC4 


Contents 
Directory sequence number. If the high-order bit of this word, UCB$V_AST_ 
ARMED, is set, it indicates that the requesting process is blocking ASTs. 


Number of times the device has been placed on line since VMS was last 
bootstrapped. 


Tape position prior to the start of the last |/O operation. 
Current tape position or frame counter. 

Position following last guaranteed successful I/O operation. 
First CRC for mount verification’s media validation. 

Second CRC for mount verification’s media validation. 
Third CRC for mount verification’s media validation. 

Fourth CRC for mount verification’s media validation. 


Figure A-20 UCB Local Disk Extension 
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Table A-—19 UCB Local Disk Extension 


Field Name 


UCB$W_DIRSEQ 
UCB$B_ONLCNT 
UCB$L_MAXBLOCK 
UCB$L_MAXBCNT 


UCB$L_DCCB 
UCB$L_MEDIA 
UCB$L_BCR 


UCBSW_EC1 


UCBSW_EC2 


UCB$W_OFFSET 
UCB$B_OFFNDX 


UCB$B_OFFRTC 


UCB$L_DX __BUF 
UCB$L_DX_BFPNT 
UCB$L__DX _RXDB 
UCBS$W_DX_BCR 
UCB$B_DX_SCTCNT 
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Directory sequence number. If the high-order bit of this word, UCB$V_AST_. 
ARMED, is set, it indicates that the requesting process is blocking ASTs. 


Number of times device has been placed on line since VMS was last 
bootstrapped. 


Maximum number of logical blocks on random-access device. This field is written 
by a disk driver during unit initialization and power recovery. 


Maximum number of bytes that can be transferred. A disk driver writes this field 
during unit initialization and power recovery. 


Pointer to cache control block. 
Media address. 


Byte-count register. Some disk drivers use this field as an internal count of the 
number of bytes left to be transferred in an 1/O request. The symbol UCB$W_ 
BCR points to the low-order word of this field. 


ECC position register. This field records the starting bit number of an error burst. 
Disk driver register dumping routines copy the contents of this field into an error 
message or diagnostic buffer. 


The VMS correction routine IOCSAPPLYECC reads the contents of this field to 
locate the beginning of an error burst in a disk block. 


ECC position register. Records the exclusive OR correction pattern. Disk driver 
register dumping routines copy the contents of this field into an error message or 
diagnostic buffer. 


The VMS ECC correction routine IOC$APPLYECC reads the contents of this field 


to correct disk data. 
Current offset register contents. 


Current offset table index. When a disk driver transfer ends in an error, the 
disk driver can retry the transfer a number of times with different offsets of the 
disk head from the centerline. This field is an index into a driver table of offset 
positions. 


Current offset retry count. This field records the number of times to try a 
particular offset setting in a disk transfer retry. 


Address of sector buffer (used by floppy-disk drivers). 

Pointer to current sector (used by floppy-disk drivers). 

Address of saved receiver-data buffer (used by floppy-disk drivers). 
Current floppy byte count (used by floppy-disk drivers). 

Current sector byte count (used by floppy-disk drivers). 
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Figure A—21 UCB Terminal Extension 
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Field Name 





UCB$L_TL_CTRLY* 
UCB$L_TL_CTRLC* 
UCB$L_TL_OUTBAND* 
UCB$L_TL_BANDOUE* 
UCB$L_TL_PHYUCB* 
UCB$L_TL_—CTLPID* 
UCB$O_TL_BRKTHRU* 
UCB$L_TT_RDUE* 
UCB$L_TT_RTIMOU* 
UCB$SL_TT_STATE1* 
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Contents 


Listhead of CTRL/Y AST control blocks (ACBs). 
Listhead of CTRL/C ACBs. 

Out-of-band character mask. 

Listhead of out-of-band ACBs. 

Address of physical UCB. 

Process ID of controlling process (used with SPAWN). 
Facility broadcast bit mask. 

Absolute time at which a read timeout is due. 
Address of read timeout routine. 

First longword of terminal state information. 

The following fields are defined within UCB$L_TT_STATE1: 


TTYSV_ST_POWER Power failure 
TTY$V_ST_CTRLS Class output 
TTY$V_ST_FILL Fill mode 
TTY$V_ST_CURSOR Cursor 
TTY$V_ST_SENDLF Forced line feed 
TTY$V_ST_BACKSPACE Backspace 
TTY$V_ST_MULTI Multi-echo 
TTY$SV_ST_WRITE Write in progress 
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Field Name 


UCBS$L_TT_STATE2* 


UCB Terminal Extension 


Contents 
TTY$V_ST_EOL 
TTY$V_ST_EDITREAD 
TTY$V_ST_RDVERIFY 
TTY$V_ST_RECALL 
TTY$V_ST_READ 
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End of line 

Editing read in progress 
Read verify in progress 
Command recall 

Read in progress 


Second longword of terminal state information. 
The following fields are defined within UCB$L_TT_STATE2: 


TTY$V_ST_CTRLO 
TTY$V_ST_DEL 
TTY$V_ST_PASALL 
TTY$V_ST_NOECHO 
TTY$V_ST_WRTALL 
TTY$V_ST_PROMPT 
TTY$V_ST_NOFLTR 
TTY$V_ST_ESC 
TTY$V_ST_BADESC 
TTY$V_ST_NL 
TTY$V_ST_REFRSH 
TTY$V_ST_ESCAPE 
TTY$V_ST_TYPFUL 
TTY$V_ST_SKIPLF 
TTY$V_ST_ESC_O 
TTY$V_ST_WRAP 
TTY$V_ST_OVRFLO 
TTY$V_ST_AUTOP 
TTY$V_ST_CTRLR 
TTY$V_ST_SKIPCRLF 
TTY$V_ST_EDITING 
TTY$V_ST_TABEXPAND 
TTY$V_ST_QUOTING 
TTY$V_ST_OVERSTRIKE 
TTY$V_ST_TERMNORM 
TTY$V_ST_ECHAES 
TTY$V_ST_PRE 
TTY$V_ST_NINTMULTI 


Output enable 

Delete 

Pass-all mode 

No echo 

Write-all mode 
Prompt 

No control-character filtering 
Escape sequence 
Bad escape sequence 
New line 

Refresh 

Escape mode 


- Type-ahead buffer full 


Skip line feed 

Output escape 

Wrap enable 

Overflow condition 

Autobaud pending 

Clock prompt and data string from read buffer 
Skip line feed following a carriage return 
Editing operation 

Expand tab characters 

Quote character 

Overstrike mode 

Standard terminator mask 

Alternate echo string 

Pre-type-ahead mode 

Noninterrupt multi-echo mode 
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Field Name 


UCB$L_TT_LOGUCB* 


UCB$L_TT_DECHAR* 
UCB$L_TT_DECHA 1+ 
UCB$L_TT_DECHA2+ 
UCB$L_TT_DECHA3* 
UCBSL_TT_WELINK* 
UCB$L_TT_WBLINK* 
UCBS$L_TT_WRTBUF* 
UCBSL_TT_MULTI« 
UCBSW_TT_MULTILEN* 
UCBSW_TT_SMLTLEN* 
UCB$L_TT_SMLT* 
UCB$W_TT_DESPEE* 
UCB$B_TT_DECRF* 
UCB$B_TT_DELFF* 
UCB$B_TT_DEPARI* 
UCB$B_TT_DETYPE* 
UCB$W_TT_DESIZE* 
UCB$W_TT_SPEED* 


UCB$B_TT_CRFILL* 
UCB$B_TT_LFFILL* 
UCB$B_TT_PARITY* 
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UCB Terminal Extension 


Contents 

TTY$V_ST_RECONNECT Reconnect operation 
TTY$V_ST_CTSLOW Clear-to-send low 
TTY$V_ST_TABRIGHT Check for tabs to the right of the current 


position 


Address of logical UCB, if the redirect bit is set (DEV$V_RED in UCB$L_ 
DEVCHAR2). If this UCB describes the logical UCB, the contents of UCB$L_ 
TT_LOGUCB are zero. 


First longword of default device characteristics. 
Second longword of default device characteristics. 
Third longword of default device characteristics. 
Fourth longword of default device characteristics. 
Write queue forward link. 

Write queue backward link. 

Current write buffer block. 

Address of current multi-echo buffer. 

Length of multi-echo string to be written. 

Saved length of multi-echo string. 

Saved address of multi-echo buffer. 

Default speed. 

Default carriage-return fill. 

Default line-feed fill. 

Default parity/character size. 

Default terminal type. 

Default line size. 


Terminal line speed. This field is read and written by the class driver, and read 
by the port driver. It contains the following byte fields: 


UCB$B_TT_TSPEED Transmit speed 
UCB$B_TT_RSPEED Receive speed 

Number of fill characters to be output for carriage return. 
Number of fill characters to be output for line feed. 


Parity, frame and stop bit information to be set when the PORT_SET_LINE 
service routine is called. This field is read and written by the class driver, and 
read by the port driver. It contains the following bit fields: 


UCB$V_TT_XXPARIT Y Reserved to DIGITAL. 
UCB$V_TT_DISPARERR Reserved to DIGITAL. 
UCB$V_TT_USERFRAME Reserved to DIGITAL. 


UCB$V_TT_LEN Two bits signifying character length (not counting 
Start, stop, and parity bits), as follows: O02 = 5 
bits; O12 = 6 bits; 102 = 7 bits; and 112 = 8 bits. 

UCB$V_TT_STOP Number of stop bits: clear if one stop bit; set if 
two stop bits. 


Table A—20 (Cont.) 


Field Name 


UCB$L_TT_TYPAHD* 
UCB$W_TT_.CURSOR* 
UCBS$B_TT_LINE* 
UCB$B_TT_LASTC* 
UCB$W_TT_BSPLEN* 
UCB$B_TT_FILL* 
UCB$B_TT_ESC* 
UCB$B_TT_ESC_O* 
UCB$B_TT_INTCNT* 
UCBSW_TT_UNITBIT# 
UCB$W_TT_HOLD 


UCB$B_TT_PREMPT 
UCB$B_TT_OUTYPE* 


UCB$L_TT_GETNXT* 
UCB$L_TT_PUTNXT* 


UCBS$L_TT_CLASS« 


UCB$L_TT_PORT 
UCB$L_TT_OUTADR 


UCB$W_TT_OUTLEN 
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UCB Terminal Extension 


Contents 


UCB$V_TT_PARITY Parity checking. This bit is set if parity checking 


is enabled. 
UCB$V_TT_ODD 
Address of type-ahead buffer. 


Parity type: clear if even parity; set if odd parity. 


Current cursor position. 

Current line position on page. 

Last formatted output character. 

Number of back spaces to output for non-ANSI terminals. 
Current fill character count. 

Current read escape syntax state. 

Current write escape syntax state. 

Number of characters in interrupt string. 

Enable and disable modem control. 


Port driver's internal flags and unit holding tank. This is read and written by the 
port driver, and is not accessed by the class driver. It contains the following 
subfields: 
TTY$B_TANK_CHAR 


TTY$V_TANK_PREMPT 
TTY$V_TANK_STOP 
TTY$V_TANK_— HOLD 
TTY$V_TANK_ BURST 
TTY$V_TANK_DMA 


Preempt character. 


Character. 

Send preempt character. 

Stop output. 

Character stored in TTY$B_TANK_CHAR. 
Burst is active. 

DMA transfer is active. 


Amount of data to be written on a callback from the class driver. When 
negative, this field indicates that there is a burst of data ready to be returned; 
when zero, it signifies that no data is to be written; and when 1, it indicates 
that a single character is to be written. This field is written by the class driver 
and read by the port driver. 


Address of the class driver’s input routine. This field is read by the port driver. 
Address of the class driver's output routine. This field is read by the port 
driver. 


Address of the class driver’s vector table. This field is initialized by the 
CLASS_CTRL_INIT macro. The port driver reads UCB$L__TT_.CLASS 
whenever it must call the class driver at an entry point other than UCB$L_ 
TT_GETNXT or UCB$L_TT_PUTNXT. 


Address of the port driver's vector table. 


Address of the first character of a burst of data to be written. This field is 
only valid when UCB$B_TT_OUTYPE contains —1. It is read and written by 
the port driver, and written by the class driver. 


Number of characters in a burst of data to be written. This field is only valid 
when UCB$B_TT_OUTYPE contains —1. It is read and written by the port 
driver, and written by the class driver. 


A-67 


Data Structures 
A.14 Unit Control Block (UCB) 


Table A—20 (Cont.) UCB Terminal Extension 


Field Name 
UCBSW__TT_PRTCTL 


UCB$B_TT_DS_RCV 
UCB$B_TT_DS_TX 
UCBSW_TT_DS_ST* 
UCBSW_TT_DS_TIM« 
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Contents 


Port driver control flags. The bits in this field indicate features that are available 
to the port; the class driver specifies which of these features are to be enabled. 


The following fields are defined within UCB$W_TT_PRTCTL. 


TTY$V_PC_NOTIME 
TTY$V_PC_DMAENA 
TTY$V_PC_DMAAVL 


TTY$V_PC_PRMMAP 


TTY$V_PC_MAPAVL 
TTY$V_PC_XOFAVL 
TTY$V_PC_XOFENA 
TTY$V_PC_NOCRLF 


TTY$V_PC_BREAK 


TTY$V_PC_PORTFDT 
TTY$V_PC_NOMODEM 
TTY$V_PC_NODISCONNECT 
TTY$V_PC_SMART_READ 
TTY$V_PC_ACCPORNAM 
TTY$V_PC_MULTISESSION 


Current receive modem. 
Current transmit modem. 
Current modem state. 
Current modem timeout. 


No timeout. If set, the terminal class driver is 
not to set up timers for output. 

DMA enabled. If set, DMA transfers are 
currently enabled on this port. 

DMA supported. If set, DMA transfers are 
supported for this port. 

Permanent map registers. If set, the port 
driver is to permanently allocate 
UNIBUS/Q22 bus map registers. 

Map registers available. If set, the port driver 
has currently allocated map registers. 

Auto XOFF supported. If set, auto XOFF is 
supported for this port. 

Auto XOFF enabled. If set, auto XOFF is 
currently enabled on this port. 

No. auto line feed. If set, a line feed is not 
generated following a carriage return. 

Break. If set, the port driver should generate 
break character; if clear, the port should turn 
off the break feature. 

FDT routine. If set, the port driver contains 
FDT routines. 

No modem. If set, the port cannot support 
modem operations. 

No disconnect. If set, the device cannot 
support virtual terminal operations. 

Smart read. If set, the port contains 
additional read capabilities. 

Access port name. If set, the port supports 
an access port name. 


Multisession terminal. If set, the port is part 
of a multisession terminal. 
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Field Name 
UCB$B_TT_MAINT* 


UCB$B_OLD* 


UCBS$L_TT_FBK* 
UCB$L_TT_RDVERIFY* 
UCB$L_TT_CLASS 1* 
UCB$L_TT_CLASS2+ 
UCB$L_TT_ACCPORNAM 
UCB$L__TP_MAP* 
UCB$B_TP_STAT 


Contents 


Maintenance functions. This field is used as the argument to the port driver's 
PORT_MAINT routine. It is written by the class driver and read by the port 
driver. 


It contains several bits that allow the following maintenance functions: 
1O$M_LOOP Set loopback mode. 


lIOSM_UNLOOP Reset loopback mode. 


lOSM_AUTXOF_ENA Enable the use of auto XON/XOFF on this line. This 
is the default. 


lIOSM_AUTXOF_DIS Disable the use of auto XON/XOFF on this line. 
lIOSM_LINE_OFF Disable interrupts on this line. 
IOSM_LINE_ON Reenable interrupts on this line. 


Reference these bits by using the mask, shifted as follows: 


BITB #I0$M_LOOP@-7,UCB$B_TT_MAINT(R5) ;Set loopback mode 


UCB$B_TT_MAINT also defines the bit UCB$V_TT_DSBL that, when set, 
indicates that the line has been disabled. 


The full name of this field is UCB$B_TT_OLDCPZORG; it currently serves as a 
filler byte. . 


Address of fallback block. 

Address of read/verify table. Reserved for future use. 
First class driver longword. 

Second class driver longword. 

Address of counted string. 

UNIBUS/Q22 bus map registers. 

DMA port-specific status. 

The following fields are defined within UCB$B_TP_STAT. 


TTY$V_TP_ABORT DMA abort requested on this line. 
TTY$V_TP_ALLOC Allocate map fork in progress. 
TTY$V_TP_DLLOC Deallocate map fork in progress. 


A-69 


B SVMS Macros Invoked by Drivers 


This appendix describes VMS macros frequently used by device drivers. 
When referring to the macro descriptions contained herein, you should be 
aware of the following conventions: 


e If an argument is enclosed in brackets, you can choose to include that 
argument or omit it. 


e VMS assigns values by default to certain arguments. If you omit one of 
these arguments, the macro behaves as if you specified the argument with 
its default value. In the macro descriptions contained in this appendix, 
the format signifies such arguments by an equal sign (=) separating the 
argument from its keyword. For example: 


SETIPL [ip|=31] 


e If an argument takes a keyword value, you should specify the keyword 
value using all uppercase letters. For example: 


preserve-YES 
condition=-RESTORE 


General information about the structure of macros and their arguments in 
general appears in the VAX MACRO and Instruction Set Reference Manual. 
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ADPDISP 


ADPDISP 


Causes a branch to a specified address given the existence of a selected 
adapter characteristic. 





FORMAT 


ADPDISP select ,adarlist [, adpaddr] [,crbaddr] [, ucbaddr] 
[,ecrbadar] [,scratch=RO] 





PARAMETERS 


select 

Determines which ADP field or bit field is the basis for dispatching and, by 
implication, which adapter characteristic. See the Description section that 
follows for a list of legal values for select. | 


addrlist 

A list containing one or more pairs of arguments in the following format: 
<flag, destination > 

The values ADPDISP accepts for flag depend upon the adapter characteristic 

specified in select and are listed in the Description section that follows. The 


destination argument contains the address to which the code generated by 
the invocation of ADPDISP passes control if the specified flag is set. 


[adpaddr] 


Register containing the address of the adapter control block. If adpaddr is not 
specified, one of the following three address fields must be specified. 


[crbaddr] 


Register containing the address of the channel request block. 


[ucbaddr] 


Register containing the address of the unit control block. 


[ecrbaddr] 


Register containing the address of the Ethernet controller data block (ECRB). 


[scratch=RO] 


Register, destroyed in macro invocation, used in computing the ADP address 
if adpaddr is not specified. 
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ADPDISP 

DESCRIPTION ADPDISP dispatches upon the following adapter characteristics: 

Possible Value of flag in 
select addrlist Definition 
ADAP_TYPE UBA, MBA, GENBI, DR, or Adapter type. 

NULL. (See those symbols 

prefixed with AT$ defined 

by the $DCDEF macro in 

SYS$LIBRARY:STARLET.MLB.) 
ADDR_BITS 18 or 22 Number of adapter address bits. 
ADAP_MAPPING YES or NO Does adapter support mapping? 
AUTOPURGE _DP YES or NO Does adapter support autopurging datapaths? 
BUFFERED_DP YES or NO Does adapter support buffered datapaths? 
DIRECT_VECTOR YES or NO Does adapter directly vector device 

interrupts? 
ODD_XFER_BDP YES or NO Does adapter support odd-aligned transfers 
over its buffered data paths? 
ODD_XFER_DDP YES or NO Does adapter support odd-aligned transfers 
. over its direct data paths? 
EXTENDED_MAPREG YES or NO Does adapter support extended set (8,192) 
map registers? 

QBUS YES or NO Is this a Q22 bus device? 


Specification of select=ADAP_TYPE causes ADPDISP to generate a CASEW 
instruction using ADP$W_ADPTYPE as an index into the case table. 
Specification of selec=ADDR-_BITS similarly causes ADPDISP to dispatch 
from the contents of ADP$B_ADDR_BITS (16 or 22 bits). If any of the other 
conditions is specified for select, ADPDISP issues a BBC or BBS instruction 
on the contents of bit field ADP$V_select in ADP$W_ADPDISP_FLAGS. 


You cannot use a single invocation of ADPDISP to dispatch on more than one 
adapter characteristic. For example, if an autopurging datapath that supports 
direct vectoring is being sought, you must use the ADPDISP macro twice. 


ADPDISP requires that the address of an ADP, CRB, UCB, or ECRB be 
specified. If anything other than an ADP is specified, the scratch register is 
used in determining the ADP address. 
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ADPDISP 
EXAMPLES 
4 ADPDISP - 
SELECT=ADAP_MAPPING, - 
ADDRLIST=<<NO, 10$>, <YES , 20$>>, - 
ADPADDR=R3 
ADPDISP transfers control to the instruction at 10$ if the adapter does not 
support mapping, or to 20$ if it does. ADPDISP uses the value in R3 to 
locate the ADP. 
E ADPDISP - 
SELECT=ADAP_TYPE, - 
ADDRLIST=<<CI, 10$>, <MBA , 20$> , <UBA, 30$>>, - 
UCBADDR=R5 , - 
SCRATCH=R1 
ADPDISP transfers control to 10$ if the adapter is a CI, 20$ if the adapter is a 
MASSBUS adapter, and 30$ if it is a UNIBUS adapter. ADPDISP determines 
the location of the ADP from a chain of pointers starting at the UCB address 
specified in R5. In doing so, it destroys the contents of scratch register R1. 
3 ADPDISP - 


SELECT=ADDR_BITS, - 
ADDRLIST=<<18, 10$> , <22, 20$>>, - 
ADPADDR=R3 


ADPDISP transfers control to 10$ for all adapters using an 18-bit address and 
20$ for all using a 22-bit address. The ADP address is supplied in R3. 


CASE 
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Generates a CASE instruction and its associated table. 





FORMAT 


CASE src ,displist [,type=W] [,limit=#0] [, nmode=S#] 





PARAMETERS 


src 
Source of the index value to be used with the CASE instruction. 


displist 
List of destinations to which control is to be dispatched, depending on the 
value of the index. 


[type=W] 
Data type of src (B, W, or L). 


[limit=#0]- 


Lower limit of the value of src. 


[nmode=S¥#] 
Addressing mode used to reference the case-table entries; the default, short- 
literal mode, is good for up to 63 entries. 





EXAMPLE 


10$: CASE - 


src=ITEMC, 


displist=<FIRST, SECOND, THIRD , FOURTH> 


This invocation of the CASE macro expands to the following code: 


CASEW  ITEMC,#0,S*#<<30001$-30000$>/2>-1 


30000$ : 
. SIGNED_WORD FIRST-30000$ 
. SIGNED_WORD SECOND-30000$ 
. SIGNED_WORD THIRD-30000$ 
. SIGNED_WORD FOURTH-30000$ 
30001$: 


B-5 


VMS Macros Invoked by Drivers 
CLASS_CTRL_INIT 3 


CLASS_CTRL_INIT 


Generates the common code that must be executed by the controller 
initialization routine of all terminal port drivers. 





FORMAT CLASS_CTRL_INIT dpt, vector 





PARAMETERS dpt 


Symbolic name of the port driver’s driver prologue table. 


vector 
Address of the port driver vector table. 





DESCRIPTION A terminal port driver’s controller initialization routine invokes the CLASS_ 
CTRL_INIT macro to relocate the class and port driver vector tables and 
perform other required initialization. 


To use the CLASS__CTRL_INIT macro, the driver must include an invocation 
of the $TTYMACS definition macro (from SYS$LIBRARY:LIB.MLB). 
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CLASS_UNIT_INIT 


Generates the common code that must be executed by the unit 
initialization routine of all terminal port drivers. 





FORMAT CLASS_UNIT_INIT 





DESCRIPTION A terminal port driver’s unit initialization routine invokes the CLASS_UNIT_ 
INIT macro to perform initialization tasks common to all port drivers. To use 
the CLASS_UNIT_INIT macro, the driver must include an invocation of the 
$TTYMACS definition macro (from SYS$LIBRARY:LIB.MLB). 


The CLASS_UNIT_INIT macro binds the terminal port and class driver into 
a single, complete driver by initializing the following UCB fields as indicated: 


Field “e633 Contents 
UCB$L_TT_CLASS Class driver vector table address 
UCB$L_TT_PORT Port driver vector table address 
UCB$L__TT_GETNXT Address of the class driver's get-next-character 
ae oan routine (CLASS_GETNXT) 

UCB$SL_TT_PUTNXT. . Address of the class driver’s put-next-character 

— routine (CLASS_PUTNXT) 
UCB$L_DDT. . Address of the terminal class driver's driver dispatch 

table 


Prior to invoking this macro, the unit initialization should place in RO the 
address of the port driver vector table. 
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CPUDISP 


Causes a branch to a specified address according to the CPU type of the 
VAX processor executing the macro code. 





FORMAT CPUDISP add*rlist ,[environ=-VMS] ,continue=NO 





PARAMETERS = addrlist 


List containing one or more pairs of arguments in the following format: 
<CPU-type, destination > 
The CPU-type parameter identifies the type or subtype of a VAX processor 


for which the macro is to generate a case table entry. The CPUDISP macro 
identifies the following VAX systems by type alone: 


CPU Type VAX System 


8PS VAX 8830/8840 

8NN VAX 8530/8550/8700/8800 
790 VAX 8600/8650/8670 

8SS VAX 8200/8250/8300/8350 
780 VAX-11/780 and VAX—11/785' 
785 VAX-11/785 

750 VAX-11/750 

730 VAX-11/730 and VAX—11/725 
UV 1 MicroVAX | 


'Because the VAX—11/785 has the same CPU type as the VAX-—11/780, the CPUDISP 
macro contains special code to distinguish between the two processors. This code tests a 
bit within the processor's system identification register (PR$_SID) that indicates whether it 
is a VAX-11/785. 


The CPUDISP macro identifies the following VAX systems by type and 
subtype: . 


CPU Type Subtype VAX System 


UV MicroVAX Il processor-based system 
UV2 MicroVAX Il 
410 VAXstation 2000/MicroVAX 2000 
CV CVAX processor-based system 
650 MicroVAX 3600-series system 
9CC VAX 6200-series system 
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You can supply any combination of generic type and subtype in a single 
invocation of the CPUDISP macro. Should the CPUDISP macro code be 
executed on the appropriate processor, the following transfers of control are 
possible: 


e If you specify a generic type but no subtype, CPUDISP causes the branch 
designated for the generic type to be taken for all of its subtypes. 


e If you specify one or more subtypes but not the generic type, CPUDISP 
causes the branch designated for each subtype to be taken. 


e If you specify both the generic type and one or more subtypes, CPUDISP 
causes the branch designated for each specified subtype to be taken. For 
those subtypes that you do not specify, CPUDISP causes the branch 
designated for the generic type to be taken. 


The destination parameter contains the address to which the code generated 
by the invocation of the CPUDISP macro passes control to continue with 
CPU-specific processing. 


[environ=VMS] 

Identification of the run-time environment of the code generated by the 
CPUDISP macro. There is no need to change the default value of this 
argument. 


continue=NO 
Specifies whether execution should continue at the line immediately after the 
CPUDISP macro if the value at EXES}GB_CPUTYPE does not correspond to 
any of the values specified as the CPU-type in the addrlist argument. A fatal 
bugcheck of UNSUPRTCPU occurs if the dispatching code does not find the 
executing processor identified in the addrlist and the value of continue is 

O. 





DESCRIPTION 


The CPUDISP macro provides a means for transferring control to a specified 
destination depending on the CPU type of the executing processor. For those 
processors that do not have a unique CPU type, CPUDISP also provides the 
means to dispatch on a particular CPU subtype. 


To accomplish this, CPUDISP builds one or two case tables. The first CASEB 
instruction uses words in the first case table to set up a transfer based on 
each CPU-type specified in the addrlist argument. CPUDISP constructs the 
second case table in the event it encounters a CPU subtype in the addrlist. 


CPUDISP constructs appropriate symbolic constants for each CPU-type listed 
in addrlist, and compares them against the contents of EXE$GB_CPUTYPE. 
These constants have the form PR$_SID_TYPCPU-type. 


For each CPU subtype it encounters in the addrlist argument, CPUDISP also 
constructs symbolic constants of the form PR$_XSID_xx_yyy, where xx is the 
generic CPU type (either UV or CV) and yyy is the CPU subtype (UV2 or 410 
for UV, or 650 or 9CC for CV). It compares the value of PR$_XSID_xx_yyy 
against the contents of EXESGB_CPUDATA+15. 
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DDTAB ie 
DDTAB 

Generates a driver dispatch table (DDT) labeled devnam$DDT. 
FORMAT ~ DDTAB  devnam ,|start=+IOCSRETURN] 


,[unsolic=HOC$RE TURN] 

,functb [,canceF+IOC$RETURN] 
[,regdmp=+lIOCSRETURN] [, diagbf=O] 
[, erlgbf=O] [,unitinit=HIOCSRETURN] 
[,altstart=+IOC$RETURN] 
[,mntver=+IOCEMNT VER] 
[,cloneducb=+IOC$RETURN] 





PARAMETERS devnam 


Generic name of the device. 


[start=+IOCSRETURN] 


Address of start-I/O routine. 


[unsolic=+lIOCSRETURN] 
Address of the routine that services unsolicited interrupts from the device. 
Only MASSBUS device drivers use this field. 


functb 


Address of the driver’s function decision table. 


[cancel=+IOCS$RETURN] 


Address of cancel-I/O routine. © 


[regdmp=+lIOCSRETURN] 


Address of the routine that dumps the device registers to an error message 
buffer or to a diagnostic buffer. 


[diagbf=O] 


Length in bytes of the diagnostic buffer. 


[erlgbf=O] 


Length in bytes of the error message buffer. 


[unitinit=+IOCSRETURN] 

Address of unit initialization routine. MASSBUS drivers should use this 
field rather than CRB$L_INTD+VEC$L—UNITINIT. UNIBUS, Q22-bus, and 
generic VAXBI drivers can use either one. 


[altstart=+IOC$RETURN] 


Address of alternate start-I/O routine. To initiate this routine, a driver 
FDT routine exits by means of VMS routine EXESALTQUEPKT instead of 
EXE$QIODRVPKT. 
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[mntver=+lIOCSMNTVER] 

Address of the VMS routine that is called at the beginning and end of a 
mount verification operation. The default, IOC6MNTVER, is suitable for all 
single-stream disk drives. Use of this field to call any other routine is reserved 
to DIGITAL. 


[cloneducb=+lIOC$RETURN] 
Address of routine called when a UCB is cloned by the $ASSIGN system 
service. 





DESCRIPTION 


The DDTAB macro creates a driver dispatch table (DDT). The table has a 
label of devnam$DDT. Just preceding the table, DDTAB generates the driver 
code program section with the following statement: 


.PSECT $$$115_DRIVER 


The DDTAB macro writes the address of the VMS universal executive 
routine vector IOC$RETURN into routine address fields of the DDT that 
are not supplied in the macro invocation (with the exception of the mntver 
argument). IOC$RETURN simply executes an RSB instruction. 


A plus sign (+) precedes the address of any specified routine that is part of 
VMS: that is, it is an address that is not relative to the location of the driver. 
No plus sign precedes the address of a routine (such as a start-I/O routine) 
that is part of the driver module. 





EXAMPLE 


DDTAB = 
DEVNAM=XX, - 
START=XX_START, - 


;DDT-creation macro 
;Name of device 
;Start-I/0 routine 


FUNCTB=XX_FUNCTABLE, - ;FDT address 


CANCEL=+IOC$CANCELI 
REGDMP=XX_REGDUMP, - 
DIAGBF=<<15*4>+<<3+ 


O;= ;Cancel-I/0 routine 
;Register dumping routine 
5+1>*4>>, - ;Diagnostic buffer size 


ERLGBF=<<15*4>+<1+*4>+<EMB$L_DV_REGSAV>> ;Error message buffer size 


This code excerpt uses the DDTAB macro to create a driver dispatch table for 
the XX device type. Note that because the cancel-I/O routine is part of VMS, 
its address is preceded by a plus sign (+). 
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$DEF 


Defines a data-structure field within the context of a $DEFINI macro. 





FORMAT $DEF sym/alloc] [,siz] 





PARAMETERS sym 


Name of the symbol by which the field is to be accessed. 
[alloc] 


Block-storage-allocation directives, one of the following: .BLKB, .BLKW, 
.BLKL, .BLKQ, or .BLKO. 


[siz] 


Number of block storage units to allocate. 





DESCRIPTION _ See the descriptions of the $DEFINI, $DEFEND, —VIELD, and $EQULST 
macros for additional information on defining symbols for data structure 
fields. 


You can define a second symbolic name for a single field, using the $DEF 
macro a second time immediately following the first definition, leaving the 
alloc argument blank in the first definition. The following example does this, 
equating SYNONYM2 with LABEL2: 


$DEFINI JLB ;Start structure definition 
$DEF LABELi .BLKL 1 ‘First JLB field 

$DEF SYNONYM2 ;Synonym for LABEL2 field 
$DEF LABEL2 .BLKL i ;Second JLB field 

$DEF LABEL3 .BLKL 1 ‘Third JLB field 

$DEFEND JLB ;End of JLB structure 


For another example of the use of the $DEF macro, see the description of the 
$DEFINI macro. 
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Ends the scope of the $DEFINI macro, thereby completing the definition of 
fields within a data structure. 
FORMAT $DEFEND struc 





PARAMETERS _ struc 


Name of the structure that is being defined. 





DESCRIPTION See the descriptions of the $DEFINI, _VIELD, and $EQULST macros for 
additional information on defining symbols for data structure fields. 
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$DEFINI 


Begins the definition of a data structure. 














FORMAT $DEFINI struc [,gb-LOCAL] [,dot=0] 
PARAMETERS _ struc 
Name of the data structure that is being defined. 
[gbI=LOCAL] | 
Specifies whether the symbols defined for this data structure are to be local or 
global symbols. The default is to make them local. 
To make the definitions of symbols global, you must specify GLOBAL for the 
value of the gbl argument. 
[dot=O] 
Offset from the beginning of the data structure of the first field to be defined. 
The $DEFINI macro moves this value into the current location counter (. ). 
DESCRIPTION _ The $DEF macro defines fields within the structure specified by the invocation 
of the $DEFINI macro, and the $DEFEND macro ends the definition. See the 
descriptions of the _VIELD and $EQULST macros for additional information 
on defining symbols for data structure fields. 
EXAMPLE 


B-14 


$DEFINI UCB, , UCB$K_LCL_DISK_LENGTH 


UCB_W_DL_PBCR 
UCB_W_DL_CS 
UCB_W_DL_BA 
UCB_A_DL_BUF_PA 
UCB_K_DL_LEN 
$DEFEND UCB 


;Start UCB extension, begin definitions 
; at end of local disk UCB extension 


.BLKW 1 ;Partial byte count 

.BLKW 1 ;Control status register 

.BLKW 1 ;Bus address register 

.BLKL 1 ;Physical buffer physical address 
.BLKW 1 ;Length of extended UCB 


This code excerpt, when assembled in VMS Version 5.0, produces the 
following symbol listing: 


UCB_A_DL_BUF_PA 000000D2 


UCB_K_DL_LEN O000000D6 
UCB$K_LCL_DISK_LENGTH = Q0Q0000CC 
UCB_W_DL_BA 000000D0 
UCB_W_DL_CS OOOQO00CE 
UCB_W_DL_PBCR 000000CC 
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DEVICELOCK 


Achieves synchronized access to a device's database as appropriate to 
the processing environment. 





FORMAT 


DEVICELOCK § /lockadadr] [,lockipl] [,savipl] [, condition] 
[,preserve=YES] 





PARAMETERS 


[lockaddr] 

Address of the device lock to be obtained. If lockaddr is not present, 
DEVICELOCK presumes that R5 contains the address of the UCB and uses 
the value at UCB$L_DLCK(RS5) as the lock address. 


[lockipl] 

Location containing the IPL at which the device database is synchronized. 

In a uniprocessing environment, the DEVICELOCK macro sets IPL to the 
specified lockip]; if no lockipl is specified, it obtains the synchronization IPL 
from the device lock’s data structure. In a multiprocessing environment, the 
VMS routine called by DEVICELOCK raises IPL to the IPL value contained in 
the device lock’s data structure, regardless of whether the lockipl argument is 
present. 


DIGITAL recommends that you specify a lockipl value to facilitate debugging. 


[savipl] 


Location at which to save the current IPL. 


[condition] 

Indication of a special use of the macro. The only defined condition is 
NOSETIPL, which causes the macro to omit setting IPL. In some instances 
setting IPL is undesirable or unnecessary when a driver obtains a device lock. 
For example, when an interrupt service routine issues the DEVICELOCK 
macro, the dispatching of the device interrupt has already raised IPL to device 
IPL 


[preserve=YES] | 
Indication that the macro should preserve RO across the invocation. If you do 
not need to retain the contents of RO, specifying preserve=NO can enhance 
system performance. 





DESCRIPTION 


In a uniprocessing environment, the DEVICELOCK macro raises IPL to lockipl 
(if condition=NOSETIPL is not specified). 


In a multiprocessing environment, the DEVICELOCK macro performs the 
following actions: 


e Preserves RO through the macro call (if preserve=YES is specified). 


e Stores the address of the device lock in RO. 
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DEVICELOCK 
¢ Calls either SMPSACQUIREL or SMP$ACQNOIPL, depending upon the 
presence of condition=NOSETIPL. SMP$ACQUIREL raises IPL to device 
IPL prior to obtaining the lock, determining appropriate IPL from the 
device lock’s data structure (SPL$B_IPL). 
In both processing environments, the DEVICELOCK macro performs the 
following tasks: 
¢ Preserves the current IPL at the specified location (if savipl is specified) 
e Sets the SMP-modified bit in the driver prologue table (DPT$V_ 
SMPMOD in DPT$L_FLAGS) 
EXAMPLE 
DEVICELOCK - 
LOCKADDR=UCB$L_DLCK(R5) ,- ;Lock device access 
LOCKIPL=UCB$B_DIPL(R5),- ;Raise IPL 
SAVIPL=- (SP) , - ;Save current IPL 
PRESERVE=YES ;Save RO 
SETIPL #31 ;Disable all interrupts 
BBC #UCB$V_POWER, - ;If clear - no power failure 


UCB$W_STS(R5) ,L1 pee 
;Service power failure! 


DEVICEUNLOCK - 


LOCKADDR=UCB$L_DLCK(R5) ,- ;Unlock device access 
NEWIPL=(SP) +, - ;Restore IPL 
PRESERVE=YES ;Save RO 
BRW RETREG ;Exit 
Li: ;Return for no power failure 
WFIKPCH RETREG, #2 ;Wait for interrupt 


The start-I/O routine of DLDRIVER invokes the DEVICELOCK macro 

to synchronize access to the device’s registers and UCB fields. Thus 
synchronized at device IPL, and holding the device lock in a VMS 
multiprocessing environment, the routine raises IPL to IPL$_POWER (IPL 
31) to check for a power failure on the local processor. If a power failure has 
occurred, the routine releases the device lock and pops the saved IPL from 
the stack before servicing the failure. If a power failure has not occurred, the 
routine branches to set up the I/O request. Note that, in this instance, it is 
the wait-for-interrupt routine, invoked by the WFIKPCH macro, that issues 
the DEVICEUNLOCK macro and pops the saved IPL from the stack. 
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DEVICEUNLOCK 


Relinquishes synchronized access to a device’s database as appropriate to 
the processing environment. 





FORMAT 


DEVICEUNLOCK = [lockadadr] [,newipl] [, condition] 
[,preserve=YES] 





PARAMETERS 


[lockaddr] 

Address of the device lock to be released or restored. If lockaddr is not 
present, DEVICEUNLOCK presumes that R5 contains the address of the UCB 
and uses the value at UCB$L_DLCK(RS) as the lock address. 


[newipl] 
Location containing the IPL to which to lower. A prior invocation of the 
DEVICELOCK macro may have stored this IPL value. 


[condition] 

Indication of a special use of the macro. The only defined condition 

is RESTORE, which causes the macro—in a VMS multiprocessing 
environment—to call SMP$RESTOREL instead of SMP$RELEASEL. This 
releases a single acquisition of the spin lock by the local processor. 


[preserve=YES] 

Indication that the macro should preserve RO across an invocation. If you do 
not need to retain the contents of RO, specifying preserve=NO can enhance 
system performance. 





DESCRIPTION 


In a uniprocessing environment, the DEVICEUNLOCK macro lowers IPL to 
newipl. If an interrupt is pending at the current IPL or at any IPL above 
newipl, the current procedure is immediately interrupted. 


In a multiprocessing environment, the DEVICEUNLOCK macro performs the 
following tasks: 


e Preserves RO through the macro call (if preserve=YES is specified). 
e Stores the address of the device lock in RO. 


e Calls SMP$RELEASEL or, if condition=-RESTORE is specified, 
SMP$RESTOREL. 


¢ Moves any specified newipl into the local processor’s IPL register (PR$_ 
IPL). If an interrupt is pending at the current IPL or at any IPL above 
newipl, the current procedure is immediately interrupted. 


In either processing environment, the DEVICELOCK macro sets the SMP- 


modified bit in the driver prologue table (DPT$V_SMPMOD in DPT$L_— 
FLAGS). 
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DEVICEUNLOCK 
EXAMPLE 
DEVICELOCK - 
LOCKADDR=UCB$L_DLCK(R5) ,- ;Lock device access 
CONDITION=NOSETIPL, - ;Do not set IPL 
PRESERVE=NO ;Do not preserve RO 
20$: MOVQ UCB$L_FR3(R5) ,R3 ;Restore driver context 
JSB @UCB$L_FPC (R5) ;Call driver at interrupt return address 


40$: DEVICEUNLOCK - 
LOCKADDR=UCB$L_DLCK(R5) ,- ;Unlock device access 
PRESERVE=NO ;Do not preserve RO 


When the device interrupts, DLDRIVER’s interrupt service routine 
immediately obtains the device lock so that it can examine device registers 
and preserve their contents. It then calls the driver’s start-I/O routine at the 
location in which it initiated device activity. The routine forks and returns 
control to the interrupt service routine, which releases the device lock. 
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DPTAB 


Generates a driver prologue table (DPT) in a program section called 


$$$ 105_PROLOGUE. 








FORMAT DPTAB end ,adapter ,[flags=O] ,ucbsize ,[unload] 
,[maxunits=8] ,[defunits=1] ,[deliver] ,[vector] 
name [, psect=$$$ 105_PROLOGUE] [, smp=NO] 
[,decode] 

PARAMETERS '- end 


Address of the end of the driver. 


adapter 


Type of adapter (as indicated by the symbols prefixed by AT$ defined by the 
$DCDEF macro in SYS$LIBRARY:STARLET.MLB). The adapter type can be 


any of the following: 


UBA UNIBUS adapter or Q22 bus interface 
MBA MASSBUS adapter 

GENBI Generic VAXBI adapter 

DR DR device 

NULL No actual device for driver 
[flags=0] 


Flags used in loading the driver. Drivers use the following flags: 


DPTSM_SVP 


DPT$M_—NOUNLOAD 


Indicates that the driver requires a permanently 

allocated system page. Disk drivers use this SPTE 
during ECC correction and when using the system 
routines IOC6MOVFRUSER and |IOC6MOVTOUSER. 


When this flag is set, the driver-loading procedure 
allocates a permanent system page-table entry (SPTE) 
for the device. It stores an index to the virtual address 
of the SPTE in UCB$L_SVPN when it creates the UCB. 
A driver can calculate the system virtual address of the 
page corresponding to this index by using the following 
formula: 

(index * 20016) + 8000000016 


Indicates that the driver cannot be reloaded. When this 
bit is set, the driver can be unloaded only by rebooting 
the system. 
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DPT$M_SMPMOD Indicates that the driver has been designed to execute 
within a VMS multiprocessing environment. Use 
of any of the VMS multiprocessing synchronization 
macros (DEVICELOCK/DEVICEUNLOCK, FORKLOCK 
/FORKUNLOCK, or LOCK/UNLOCK) automatically sets 
this flag, as long as the code using the macro resides 
in the same module as the invocation of DPTAB. 


ucbsize 

Size in bytes of each UCB the driver-loading procedure creates for devices 
supported by the driver. This required argument allows drivers to extend 
the UCB to store device-dependent data describing an I/O operation. 
Figure A-17 describes the VMS-defined extensions to the UCB and discusses 
the means by which a driver can define a device-specific extension. 


[unload] 
Address of the driver routine invoked by the SYSGEN RELOAD command 
before it unloads an old version of the driver to load a new version. The 


driver-loading procedure calls this routine before reinitializing all controllers 


and device units associated with the driver. 


[maxunits=8] 

Maximum number of units that this driver supports on a controller. This field 
affects the size of the IDB created by the driver-loading procedure. If you 
omit the maxunits argument, the default is eight units. You can override 
the value specified in the DPT by using the /MAXUNITS qualifier to the 
SYSGEN CONNECT command. 


[defunits=1 ] 

Maximum number of UCBs to be created by SYSGEN’s AUTOCONFIGURE 
command (one for each device unit to be configured). The unit numbers 
assigned are zero through defunits—1. 


If you do not specify the deliver argument, AUTOCONFIGURE creates 
the number of units specified by defunits. If you specify the address of a 
unit delivery routine in the deliver argument, AUTOCONFIGURE calls that 
routine to determine whether or not to create each UCB automatically. 


[deliver] 


Address of the driver unit delivery routine. The unit delivery routine 
determines which device units supported by this driver the SYSGEN 
AUTOCONFIGURE command should configure automatically. If you omit 
the deliver argument, the AUTOCONFIGURE command creates the number 
of units specified by the defunits argument. 


[vector] 
Address of a driver-specific transfer vector. A terminal port driver specifies 
the address of its vector table in this argument. 


name 

Name of the device driver. The driver-loading procedure will permit the 
loading of only one copy of the driver associated with this name. A driver 
name can be up to 11 alphabetic characters and, by convention, is formed 
by appending the string DRIVER to the 2-alphabetic-character generic device 
name, for example, DBDRIVER. 


DESCRIPTION 


EXAMPLE 


DPTAB 


DPT_STORE 
DPT_STORE 


DPT_STORE 
DPT_STORE 


DPT_STORE 
DPT_STORE 
DPT_STORE 
DPT_STORE 
DPT_STORE 
DPT_STORE 
DPT_STORE 


DPT_STORE 
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[psect=$$$ 105_PROLOGUE] 


Program section in which the DPT is created. The default value of this 
argument is required for all non-DIGITAL-supplied device drivers. 


[smp=NO] 

Indication of whether the driver is suitably synchronized to execute in a VMS 
multiprocessing system. Note that use of any of the spin lock synchronization 
macros in a device driver causes the DPTAB macro to indicate multiprocessing 
synchronization. 


[decode] 


Offset to name used by workstation windowing software. 





The DPTAB macro, in conjunction with invocations of the DPT_STORE 
macro, creates a driver prologue table (DPT). The DPTAB macro places 
information in the DPT that allows the driver-loading procedure to determine 
the identity of the driver and the devices it supports. The DPTAB macro, 

in invoking the $SPLCODDEF definition macro, also defines the spin lock 
indexes used in the DPT_STORE, FORKLOCK, and LOCK macros. 





- ;DPT-creation macro 

END=XA_END, - ;End of driver label 

ADAPTER=UBA, - ;Adapter type 

FLAGS=<DPT$M_SVP! - ;Allocate permanent SPTE 
DPT$M_SMPMOD> , - ;Multiprocessing driver 

UCBSIZE=UCB$K_SIZE, - ;UCB size 

NAME=XADRIVER ;Driver name 

INIT ;Start of load initialization table 

UCB , UCB$B_FLCK ,B, - 

SPL$C_IOLOCK8 
UCB, UCB$B_DIPL,B, 22 
UCB , UCB$L_DEVCHAR, L, <- 


;Fork lock index 
;Device interrupt IPL 
;Device characteristics 


DEV$M_AVL! - ; Available 

DEV$M_RT™! - ;Real time device 
DEV$M_ELG! - ;Error logging enabled 
DEV$M_IDV! - ;Input device 
DEV$M_ODV> ;Output device 


UCB , UCB$B_DEVCLASS ,B, - 
DC$_REALTIME 

UCB, UCB$B_DEVTYPE, B, - 
DT$_DR11W 

UCB , UCB$W_DEVBUFSIZ,W, - 
XA_DEF_BUFSIZ 


;Device class 
;Device type 


;Default buffer size 
REINIT ;Start of reload initialization table 
DDB,DDB$L_DDT,D,XA$DDT ;Address of DDT 
CRB, CRB$L_INTD+VEC$L_ISR,D, - 

XA_INTERRUPT ;Address of interrupt service routine 
CRB, CRB$L_INTD+VEC$L_INITIAL,D, - 

XA_CONTROL_INIT ;Address of controller initialization routine 
END ;End of initialization 
This excerpt from XADRIVER.MAR contains the DPTAB macro and the series 
of DPT_STORE macros that create its driver prologue table. 
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DPT_STORE 


Instructs the VMS driver-loading procedure to store values in a table or 
data structure. 





FORMAT DPT_STORE §str_type,str_off ,oper ,exp [,pos] [, size] 





PARAMETERS _ str_type 
Type of data structure (CRB, DDB, IDB, ORB, or UCB) into which the driver- 
loading procedure is to store the specified data, or a label denoting a table 
marker. Table marker labels indicate the start of a list of DPT_STORE macro 
invocations that store information for the driver-loading procedure in the 
driver initialization table and driver reinitialization table sections of the DPT. 
If this argument is a table marker label, no other argument is allowed. The 
following labels are used: 


INIT Indicates the start of fields to initialize when the driver is loaded 

REINIT Indicates the start of additional fields to initialize when the driver is 
loaded and reinitialized when the driver is reloaded 

END Indicates the end of the two lists 

str_off 


Unsigned offset into the data structure in which the data is to be stored. This 
value cannot be more than 65,535 bytes. 


oper 
Type of storage operation, one of the following: 


Type Meaning 

B Write a byte value. 

W Write a word value. 

L Write a longword value. 

D Write an address relative to the beginning of the driver. 

V Write a bit field. If you specify a V in the oper argument, the 


driver-loading procedure uses the exp, pos, and size arguments as 
operands to an INSV instruction. 


If an at sign (@) precedes the oper argument, the exp argument indicates the 
address of the data that is to be stored and not the data itself. 
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exp 
Expression indicating the value with which the driver-loading procedure 

is to initialize the indicated field. If an at-sign character (@) precedes the 
oper argument, the exp argument indicates the address of the data with 
which to initialize the field. For example, the following macro indicates that 
the contents of the location DEVICE_CHARS are to be written into the 
DEVCHAR field of the UCB. 


DPT_STORE UCB,UCB$L_DEVCHAR, @L, DEVICE_CHARS 


[pos] 


Starting bit position within the specified field; used only if oper=V. 


[size] 
Number of bits to be written; used only if oper=V. 





DESCRIPTION 


The DPT_STORE macro places information in the DPT that the driver- 
loading procedure uses to load specified values into specified fields. The 
DPT_STORE macro accepts two lists of fields: 


e Fields to be initialized only when a driver is first loaded 


e Fields to be initialized when a driver is first loaded and reinitialized if the 
driver is reloaded 


The DPTAB macro stores the relative addresses of these two lists, called 
initialization and reinitialization tables, in the DPT. A driver constructs 
the initialization tables by following the DPTAB macro with one or more 
invocations of the DPT_STORE macro. 


Drivers use the DPT_STORE macro with the INIT table marker label to 
begin a list of DPT_STORE invocations that supply initialization data for the 
following fields: 


UCB$B_FLCK Index of the fork lock under which the driver performs 
fork processing. Fork lock indexes are defined by the 
$SPLCODDEF definition macro (invoked by DPTAB) as 


follows: 

IPL Fork Lock Index 

8 SPL$C_IOLOCK8 

9 SPL$C_IOLOCK9 

10 SPL$C_IOLOCK 10 

11 SPL$C_IOLOCK1 1 
UCB$B_DIPL Device interrupt priority level. 
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Other commonly initialized fields are as follows: 


UCB$L_DEVCHAR 
UCB$B_DEVCLASS 
UCB$B_DEVTYPE 
UCB$W_DEVBUFSIZ 
UCB$O_DEVDEPEND 


Device characteristics. 

Device class. 

Device type. 

Default buffer size. 
Device-dependent parameters. 


Drivers use the DPT_STORE macro with the REINIT table marker label 
to begin a list of DPT_STORE invocations that supply initialization and 
reinitialization data for the following fields: 


DDB$L_DDT 


CRB$L_INTD+ 
VEC$L_ISR 


CRB$L_INTD2+ 
VEC$L_ISR 


CRB$L_INTD+ 
VECS$L_INITIAL 


CRB$L_INTD+ 
VEC$L_UNITINIT 


Driver dispatch table. Every driver must specify a value 
for this field. 


Interrupt service routine. 
Interrupt service routine for second interrupt vector. 
Controller initialization routine. 


Unit initialization routine (for UNIBUS, Q22 bus, and 
generic VAXBI device drivers). Note that MASSBUS 
drivers must specify the address of the unit initialization 
routine in an invocation of the DDTAB macro. 


For an example of the use of the DPT_STORE macro, see the description of 


the DPTAB macro. 
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Blocks interrupts from occurring on the local processor at or below a 
specified IPL. 





FORMAT 


DSBINT  [ipF31] [,dst-—(SP)] 
[,environ=MULTIPROCESSOR] 





PARAMETERS 


“MACRO-W-GENWARN, Generated WARNING: Raising IPL to #xx provides 


[ipl=31] 
IPL at which to block interrupts. If no ipl is specified, the default is IPL 31, 
which blocks all interrupts. 


[dst=—(SP)] 


Location in which to save the current IPL. If no destination is specified, the 
current IPL is pushed onto the stack. 


[environ=MULTIPROCESSOR] 


Processing environment in which the DSBINT synchronization macro 

is to be assembled. If you do not specify environ, or if you do specify 
environ-MULTIPRQCESSOR, the DSBINT macro generates the following 
assembly-time warning message, where xx is an IPL above IPL 2: 


ultiprocessing synchronization 






If you are certain that the purpose o cro invocation is to block only 
local processor events, you can disable the warning message by including 
environ-UNIPROCESSOR in the invocation. 





DESCRIPTION 


The DSBINT macro first stores the current IPL of the local processor and then 
moves the specified IPL into the processor’s IPL register (PR$_IPL). 


Note that the DSBINT and ENBINT macros provide full synchronization 
only in a uniprocessing environment. In a multiprocessor configuration, 
DSBINT and ENBINT are suitable only for blocking events on the local 
processor. To provide synchronized access to system resources and 
devices in a multiprocessing environment, you must use the DEVICELOCK 
/DEVICEUNLOCK, FORKLOCK/FORKUNLOCK, and LOCK/UNLOCK 
macros. 
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ENBINT 


Lowers the local processor’s IPL to a specified value, thus permitting 
interrupts to occur at or beneath the current IPL. 





FORMAT ENBINT [src-(SP)+]_ 





PARAMETERS = [src=(SP)+] 
Location containing the IPL to be restored to the processor IPL register (PR$_ 
IPL) of the local processor. If you do not specify a value in src, ENBINT 
moves the value on the top of the stack into PR$_IPL. 





DESCRIPTION | The ENBINT macro complements the actions of the DSBINT macro, restoring 
an IPL value to PR$_IPL. Procedures invoke this macro to lower IPL to a 
previously saved level. If an interrupt is pending at the current IPL or at 
any IPL above the IPL eae by src, the current procedure is immediately 
interrupted. 


Note that the DSBINT and ENBINT macros only provide full synchronization 
in a uniprocessor environment. In multiprocessor configurations, 

DSBINT and ENBINT are only suitable for blocking events on the local 
processor. To provide synchronized access to system resources and 

devices in a multiprocessing environment, you must use the DEVICELOCK 

7 DEVICEUNEVES FORKLOCK/FORKUNLOCK, and LOCK/UNLOCK 
macros. 
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$EQULST 


Defines a list of symbols and assigns values to the symbols. 





FORMAT $EQULST prefix ,[gbF LOCAL] , init ,[incr=1] , list 





PARAMETERS _ prefix 


Prefix to be used in forming the names of the symbols. 


[gblI=-LOCAL] 
Scope of the definition of the symbol, either LOCAL, the default, or 
GLOBAL. 


init 
Value to be assigned to the first symbol in the list. 


[iner=1] 
Increment by which to increase the value of each succeeding symbol in the 
list. The default is 1. 


list 
List of symbols to be defined. Each element in the list can have one of the 
following forms: 


<symbol> — where symbol is the string appended to the prefix, 
forming the name of the symbol; the value of the symbol is assigned 
based on the values of init and incr. 

<symbol,value> — where symbol is the string that is appended to the 
prefix, forming the name of the symbol, and value specifies the value of 
the symbol. 





DESCRIPTION _ See the descriptions of the $DEFINI and —VIELD macros for additional 
information on defining symbols for data structure fields. 





EXAMPLE 


$EQULST XA_K_,,0,1,<- ;Define CSR bit values 

<fnct1,2>- 

<fnct2,4>- 

<fnct3, 8>- 

<statusa, 2048>- 

<statusb, 1024>- 

<statusc,512>- 

> 


VMS Macros Invoked by Drivers 
$EQULST 


This code excerpt produces the following symbols: 


XA_K_FNCT1 = 00000002 
XA_K_FNCT2 = 00000004 
XA_K_FNCT3 = 00000008 
XA_K_STATUSA = 00000800 
XA_K_STATUSB = 00000400 
XA_K_STATUSC = 00000200 
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FIND_CPU_DATA 


Locates the start of the current process’s per-CPU database area (CPU). 





FORMAT 


FIND_CPU_DATA reg [,amod=GJ [,istack=NO] 





PARAMETERS 


reg 
Register to receive the base virtual address of the current processor’s per-CPU 
database structure (CPU)). 


[amod=G] 


Addressing mode. 


[istack=NO] 

Mechanism by which the base of the per-CPU database structure is calculated. 
Use istack=YES used only when it is certain that the processor is executing 
on the interrupt stack. The mechanism used when istack=NO is somewhat 
slower, but works whether the processor is executing on the interrupt stack or 
kernel stack. 





DESCRIPTION 


The FIND_-CPU_DATA macro loads the starting virtual address of the 
current processor’s per-CPU database (CPU) into the specified register. A 
driver generally invokes the FIND_CPU_DATA macro in the process of 
determining the current process of the current CPU when executing in system 
context. 


Such a driver must adhere to the following rules: 


e It must invoke the FIND_CPU_DATA macro in kernel mode at or above 
IPL$_RESCHED. 


e It must ensure that it will not be rescheduled after issuing the macro 
while it is using the information returned by FIND_-CPU_DATA. It 
typically does this by remaining at IPL$RESCHED or greater. 





EXAMPLE 


FIND_CPU_DATA RO 


MOVL CPU$L_CURPCB(RO) ,R1 


The FIND_CPU_DATA macro returns the starting virtual address of the 
current processor’s per-CPU database in RO. The subsequent MOVL 
instruction obtains the address of the process currently active on that 
processor and places it in R1. 
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FORK 


Creates a fork process, in which context the code that follows the macro 
invocation executes. 





FORMAT FORK 





DESCRIPTION _ The FORK macro calls EXE$FORK to create a fork process. When the FORK 
macro is invoked, the following registers must contain the values listed: 


Register Contents 

R3 Contents to be placed in R3 of the fork process 
R4 Contents to be placed in R4 of the fork process 
R5 Address of fork block 

OO(SP) Address of caller’s caller 


Unlike EXE$IOFORK, EXE$FORK does not disable device timeouts by clearing 
the UCB$V_TIM bit in the field UCB$L_STS. 


FORKLOCK 
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Achieves synchronized access to a device driver's fork database as 
appropriate to the processing environment. 





FORMAT 


FORKLOCK = [lock] [,lockipl] [, savipl] [, preserve=YES] 
[, fipNO] 





PARAMETERS 


[lock] 

Index of the fork lock to be obtained. If the lock argument is not present in 
the macro invocation, FORKLOCK presumes that R5 contains the address of 
the fork block and uses the value at FKB$B_FLCK(RS) as the lock index. 


[lockipl] 

Location containing the IPL at which the fork database is synchronized. 
Although the value of this argument is ignored by the macro, DIGITAL 
recommends that you specify a lockipl value to facilitate debugging. 


[savipl] 


Location at which to save the current IPL. 


[preserve=YES] 

Indication that the macro should preserve RO across the invocation. If you do 
not need to retain the contents of RO, specifying preserve=NO can enhance 
system performance. ; 


[fipFNO] 
Indication that the macro does not need to determine whether the contents of 
the lock argument or FKB$B_FLCK(RS) is a fork lock index or a fork IPL. The 
FORKLOCK macro ignores the contents of this argument in a multiprocessing 
environment. 


The VMS fork dispatcher uses fipl-YES to determine whether a fork block it 
is servicing contains a fork lock index or a fork IPL. Because a device driver 
initializes offset UCB$B_FLCK (also known as UCB$B_FIPL) in the fork 
block, it does not need to determine its contents when it issues a FORKLOCK 
macro. 





DESCRIPTION 


In a uniprocessing environment, the FORKLOCK macro raises IPL according 
to one of the following methods: 


e It sets IPL to the IPL that corresponds to the fork lock index in the spin 
lock IPL vector (SGMP$AR_IPLVEC). 
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FORKLOCK 
e If you specify fipI-YES, the FORKLOCK macro takes the following 
actions: 

— If offset FKB$B_FLCK (FKB$B_FIPL) contains a fork lock index, it 
sets IPL to the IPL that corresponds to the fork lock index in the spin 
lock IPL vector (SMP$AR_IPLVEC). 

— If offset FKB$B_FLCK (FKB$B_FIPL) contains a fork IPL, it sets IPL 
to that fork IPL. 

In a multiprocessing environment, the FORKLOCK macro stores the fork lock 
index in RO and calls SMP$ACQUIRE. SMP$ACQUIRE uses the value in RO 
to locate the fork lock structure in the system spin lock database (a pointer 
to which is located at SMP$AR_SPNLKVEC). Prior to securing the fork lock, 
SMP$ACQUIRE raises IPL to its associated IPL (SPL$B_IPL). 
In both processing environments, the FORKLOCK macro performs the 
following tasks: 
e Preserves RO through the macro call (if preserve=YES is specified) 
e Preserves the current IPL at the specified location (if savipl is specified) 
e Sets the SMP-modified bit in the driver prologue table (DPT$V_ 
SMPMOD in DPT$L—FLAGS) 
EXAMPLE 
FORKLOCK - 
LOCK=UCB$B_FLCK(R5) , - ;Lock fork database 
SAVIPL=- (SP) , - ;Save the current IPL 
PRESERVE=NO0 ;Do not preserve RO 
INCW UCB$W_QLEN(R5) ;Bump device queue length 
BBSS #UCB$V_BSY , UCB$W_STS(R5) , - 
20$ ;If set, device is busy 
PUSHL R65 ;Save UCB address 
BSBW IOC$INITIATE ;Initiate I/O function 
POPL R5 ;Restore UCB address 
FORKUNLOCK - 
LOCK=UCB$B_FLCK(R5) ,- ;Unlock fork database 
NEWIPL=(SP)+, - ;Restore previous IPL 
PRESERVE=NO0 ;Do not preserve RO 
RSB 
208: ;Place IRP in UCB pending-I/0 queue 


The VMS routine that determines whether a device can immediately service 
an I/O request synchronizes its access to the fork database by invoking the 
FORKLOCK macro. The FORKLOCK macro raises IPL to fork IPL and, in a 
multiprocessing environment, obtains the corresponding fork lock. 


Thus synchronized, the VMS routine tests a bit in the UCB to determine 
whether the device is busy. If the device is not busy, VMS calls a routine 
that initiates driver processing of the I/O request, still at fork IPL and holding 
the fork lock. Later, possibly with an invocation of the WFIKPCH macro, 
the driver start-I/O routine returns control to this routine, which issues the 
FORKUNLOCK macro to relinquish fork level synchronization. 
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FORKUNLOCK 


Relinquishes synchronized access to a device driver’s fork database as 
appropriate to the processing environment. 





FORMAT 


FORKUNLOCK [lock] [,newipl] [, condition] 
[,preserve=YES] 





PARAMETERS 


[lock] 

Index of the fork lock to be released or restored. If lock is not present, 
FORKUNLOCK assumes that R5 contains the address of the fork block and 
uses the value at FKB$B_FLCK(R5) as the fork lock index. 


[newipl] 
Location containing the IPL to which to lower. A prior invocation of the 
FORKLOCK macro may have stored this IPL value. 


[condition] 

Indication of a special use of the macro. The only defined condition 
is RESTORE, which causes the macro—in a VMS multiprocessing 
environment—to call SMP$RESTORE instead of SMP$RELEASE. This 
releases a single acquisition of the fork lock by the local processor. 


[preserve=YES] 

Indication that the macro should preserve RO across an invocation. If you do 
not need to retain the contents of RO, specifying preserve=NO can enhance 
system performance. 





DESCRIPTION 


In a uniprocessing environment, the FORKUNLOCK macro lowers IPL to 
newipl. If an interrupt is pending at the current IPL or at any IPL above 
newipl, the current procedure is immediately interrupted. 


In a multiprocessing environment, the FORKUNLOCK macro performs the 
following tasks: 


¢ Preserves RO through the macro call (if preserve=YES is specified). 
e Stores the fork lock index in RO. 


¢ Calls SMP$RELEASE or, if condition=RESTORE is specified, 
SMP$RESTORE. 


¢ Moves any specified newipl into the local processor’s IPL register (PR$_ 
IPL). If an interrupt is pending at the current IPL or at any IPL above 
newipl, the current procedure is immediately interrupted. 


In either processing environment, the FORKUNLOCK macro sets the SMP- 
modified bit in the driver prologue table (DPT$V_SMPMOD in DPT$L— 
FLAGS). 


For an example of the use of the FORKUNLOCK macro, see the description 
of the FORKLOCK macro. 
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FUNCTAB 





FORMAT 





PARAMETERS 





DESCRIPTION 


Creates a driver's function decision table (FDT) and generates FDT entries. 


FUNCTAB [action] ,codes 


[action] 
Address of an FDT routine that VMS calls when preprocessing an I/O request 
whose function code matches a function. indicated in the codes argument. A 
plus sign (+) precedes the address of any specified FDT routine that is part of 
VMS. No plus sign precedes the address of an FDT routine that is contained 
within the driver module. | 


You cannot specify an action argument in a driver's first two invocations of 
the FUNCTAB macro. 


codes 
List of I/O function codes that VMS preprocessing services by calling the FDT 
routine specified in the action argument of the FUNCTAB macro invocation. 


The macro expansion prefixes each code with the string IO$_; for example, 
READVBLK expands to IO$_READVBLK. 


A device driver uses several invocations of the FUNCTAB macro to generate 
the three components of a function decision table: 


e §=6The list of valid I/O function codes 
e The list of buffered I/O function codes 


e One or more FDT entries 


The first two invocations of the FUNCTAB macro in a driver generate the 
lists of valid I/O functions and buffered I/O functions, respectively. These 
invocations include the codes argument, but not the action argument. If no 
buffered I/O functions are defined for the device, the codes argument to the 
second invocation of the FUNCTAB macro specifies an empty list. 


Each succeeding invocation of the FUNCTAB macro generates an FDT entry. 
Each FDT entry specifies all or a subset of the valid I/O function codes and 
the address of an FDT routine that performs I/O preprocessing for those 
function codes. You can specify any valid I/O function code in more than 
one of these FUNCTAB macro invocations, thus causing more than one FDT 
routine to be called for a single valid I/O function code. 
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EXAMPLE 


XX_FUNCTABLE: 


FUNCTAB 


FUNCTAB 


FUNCTAB 


FUNCTAB 


FUNCTAB 


;Function decision table 
a ;Valid functions 
<READLBLK , - ;Read logical block 


READPBLK, - ;Read physical block 
READVBLK, - ;Read virtual block 
SENSEMODE, - ;Sense reader mode 

SENSECHAR  , - ;Sense reader characteristics 
SETMODE, - ;Set reader mode 

SETCHAR, - ;Set reader characteristics 
> 

7 ;Buffered-I/0 functions 
<READLBLK , - ;Read logical block 

READPBLK, - ;Read physical block 
READVBLK, - ;Read virtual block 
SENSEMODE, - ;Sense reader mode 

SENSECHAR, - ;Sense reader characteristics 
SETMODE, - ;Set reader mode 

SETCHAR, - ;Set reader characteristics 
> 
XX_READ, - ;Read function FDT routine 
<READLBLK , - ;Read logical block 

READPBLK, - ;Read physical block 
READVBLK, - ;Read virtual block 
> 

+EXE$SETMODE, - ;Set mode/characteristics FDT routine 
<SETCHAR, - ;Set reader characteristics 
SETMODE, - ;Set reader mode 
> 

+EXE$SENSEMODE, - ;Sense mode/characteristics FDT routine 
<SENSECHAR, - ;Sense reader characteristics 
SENSEMODE, - ;Sense reader mode 
> 


This function decision table specifies that the routine XX_READ be called for 
all read functions that are valid for the device. XX_READ appears later in 
the driver module. VMS I/O preprocessing will call routines EXESSETMODE 
and EXE$SENSEMODE for the device’s set-characteristics and sense-mode 
functions. Because each of these routines is part of VMS, a plus sign (+) 
precedes its name in the FUNCTAB macro argument. 
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IFNORD, IFNOWRT, IFRD, IFWRT 


Determines the read or write accessibility of a range of memory locations. 





FORMAT IFNORD 


eo siz ,adr ,dest [, mode=#0] 


IFWRT 





PARAMETERS - siz 
Offset of the last byte to check from the first byte to check, a number less 
than or equal to 512. 


adr 

Address of first byte to check. 

dest 

Address to which the macro transfers control, according to the following 

conditions: 

Macro Condition 

IFNORD If either of the specified bytes cannot be read in the specified 
access mode 

IFNOWRT If either of the specified bytes cannot be written in the specified 
access mode 

IFRD If both bytes can be read in the specified access mode 

IFWRT If both bytes can be written in the specified access mode 

[mode=#0] 


Mode in which access is to be checked; zero, the default, causes the check to 
be performed in the mode contained in the previous-mode field of the current 
PSL. 





DESCRIPTION The IFNORD and IFRD macros use the PROBER instruction to check the read 
accessibility of the specified range of memory by checking the accessibility of 
the first and last bytes in that range. The IFNORD macro passes control to 
the specified destination if either of the specified bytes cannot be read in the 
specified access mode. The IFRD macro transfers control if both bytes can be 
read in the specified access mode. Otherwise, the macros transfer to the next 
in-line instruction. 
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The IFNOWRT and IFWRT macros use the PROBEW instruction to check 
the write accessibility of the specified range of memory by checking the 
accessibility of the first and last bytes in that range. The IINOWRT macro 
‘passes control to the specified destination if either of the specified bytes 
cannot be written in the specified access mode. The IFWRT macro transfers 
control to the specified destination if both bytes can be written in the specified 
access mode. Otherwise, the macros transfer to the next in-line instruction. 





EXAMPLE 
MOVZWL $SS_ACCVIO, RO ;Assume read access failure 
MOVL ENTRY_LIST(AP) ,R11 ;Get address of entry point list 
IFRD #4%4, (R11) ,50$ ;Branch forward if process 
; has read access 
BRW ERROR ;Otherwise stop with error 


The connect-to-interrupt driver uses the IFRD macro to verify that the process 
has read access to the four longwords that make up the entry point list. The 
address of the entry point list was specified in the p2 argument of the $QIO 
request to the driver. 
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INVALIDATE_TB 


Flushes a single page-table entry (PTE) or all PTEs from the translation 
buffers of all processors in a VAX system. 





FORMAT 


INVALIDATE_TB [addr] [,reg] [,inst1] [,inst2] [,inst3] 





PARAMETERS [addr] 


Virtual address mapped by the PTE for which invalidation is required. If addr 
is blank, then the macro invalidates all PTEs in the translation buffer. 


[reg] 


Register into which the macro moves the value of addr. 


[inst1] 


First instruction that writes the PTE. 


[inst2] 


Second instruction that writes the PTE. 


[inst3] 


Third instruction that writes the PTE. 





DESCRIPTION 


When privileged code alters page mapping information, modifying a 

valid PTE in an active page table, it must remove the stale value of that 
PTE from any translation buffers that may have cached it, both on the 
processor performing the modifications and on any other processor in a VMS 
multiprocessing system. 


You must use the INVALIDATE_TB macro to flush the stale value of a 
previously valid PTE from the translation buffer of any processor in a VAX 
system and execute up to three instructions that modify the PTE while all 
processors are prevented from referencing that page. If you do not supply an 
addr argument, the INVALIDATE_TB macro invalidates all translation buffer 
entries. 


INVALIDATE_TB executes the instructions supplied in the macro invocation 
as part of a coroutine call to SMP$INVALID. These instructions, therefore, 
should not reference the stack and should not use R2. Note that the 
INVALIDATE_TB macro destroys the contents of R2. 


To invoke INVALIDATE_TB, code must be executing at or below IPL$_ 
INVALIDATE, holding—in a VMS multiprocessing environment—no spin 
lock ranked higher than INVALIDATE. If you issue the INVALIDATE_TB 
macro from pageable code, you must ensure that the location of the code has 
been locked in memory. 
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EXAMPLE 
MOVL 8(SP) ,R2 :Load virtual address to invalidate 
MOVL 12(SP) ,R3 ;Load address of PTE 
INVALIDATE_TB R2,- :Invalidate translation buffer 


INST1=<BICL2 #PTE$M_VALID,(R3)> ;Clear PTE valid bit 


The INVALIDATE_TB macro causes the PTE corresponding to the virtual 
address supplied in R2 to be flushed from the system’s translation buffers. 
The macro causes the specified BICL2 instruction to be executed while other 
‘processors in the system are prevented from referencing the stale PTE. 
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IOFORK 


Disables timeouts from a target device and creates a fork process, in 
which context the code that follows the macro invocation executes. 











FORMAT lIOFORK 
DESCRIPTION — The IOFORK macro calls EXE$IOFORK to disable timeouts from a target 
device (by clearing UCB$V_TIM in UCB$L_STS) and to create a fork process 
for a device driver. 
When the IOFORK macro is invoked, the following registers must contain the 
values listed: 
Register Contents 
R3 Contents to be placed in R3 of the fork process 
R4 Contents to be placed in R4 of the fork process 
R5 Address of a UCB that will be used as a fork block for the fork 
process to be created 
00(SP) Address of caller's caller 
EXAMPLE 
WFIKPCH XA_TIME_OUT, IRP$L_MEDIA(R3) ;Wait for interrupt 
IOFORK ;Device has interrupted; fork 
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The start-I/O routine of a driver initiates an I/O request by invoking the 
WFIKPCH macro. The WFIKPCH macro sets UCB$V_INT and UCB$V_TIM 
in UCB$L_STS to record an expected interrupt and enable timeouts from the 
device, saving the PC of the instruction following IOFORK at UCB$L_FPC 
in the driver’s fork block. When the device interrupts, the driver’s interrupt 
service routine clears UCB$V_INT and issues the instruction JSB @UCB$L_ 
FPC(R5), transferring control to the IOFORK macro invocation. 


The IOFORK macro clears the UCB$V_TIM bit, creates a fork block, inserts 
it in the appropriate fork queue, requests a software interrupt at that fork IPL 
from the local processor, and returns control to the driver’s interrupt service 
routine at the instruction following the JSB. When the processor’s IPL drops 
below the fork level, the fork dispatcher dequeues the fork block, obtains 
proper synchronization, and resumes execution at the instruction in the driver 
that follows the IOFORK invocation. 
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LOADALT 


Loads a set of Q22-bus alternate map registers. 





FORMAT LOADALT 





DESCRIPTION The LOADALT macro calls IOC$LOADALTMAP to load a set of Q22 bus 
alternate map registers (registers 496 to 8191). Map registers must already be 
allocated before the LOADALT macro can be invoked. 


When the LOADALT macro is invoked, register R5 must contain the address 
of the UCB. LOADALT destroys the contents of RO through R2. 
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LOADMBA 
LOADMBA 

Loads MASSBUS map registers. 
FORMAT LOADMBA 





DESCRIPTION = The LOADMBA macro calls IOC$LOADMBAMAP to load MASSBUS map 
registers. The driver must own the MASSBUS adapter, and thus the map 
registers, before it can invoke LOADMBA. 


When the LOADMBA macro is invoked, the following registers must contain 
the following values: 


Register Contents 
R4 Address of the MBA's configuration register (MBA$L_—CSR) 
R5 Address of UCB 


LOADMBA destroys the contents of RO through R2. 
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LOADUBA 


Loads a set of UNIBUS map registers or a set of the first 496 Q22-bus 
map registers. 





FORMAT LOADUBA 





DESCRIPTION The LOADUBA macro calls IOC$LOADUBAMAP to load a set of UNIBUS 
map registers or a set of the first 496 Q22-bus map registers. Map registers 
must already be allocated before the LOADUBA macro can be invoked. 


When the LOADUBA macro is invoked, register R5 must contain the address 
of the UCB. LOADUBA destroys the contents of RO through R2. 
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LOCK 


Achieves synchronized access to a system resource as appropriate to the 
processing environment. 





FORMAT 


LOCK /lockname [,lockipl] [,savipl] [,condition] 
[preserve=YES] 





PARAMETERS 


lockname 
Name of the resource to lock. 


[lockipl] 
Location containing the IPL at which the resource is synchronized. Although 


the value of this argument is ignored by the macro, DIGITAL recommends 
that you specify a lockip] value to facilitate debugging. 


[savipl] 


Location at which to save the current IPL. 


[condition] 
Indication of a special use of the macro. The only defined condition is 
NOSETIPL, which causes the macro to omit setting IPL. 


[preserve=YES] 

Indication that the macro should preserve RO across the invocation. If you do 
not need to retain the contents of RO, specifying preserve=NO can enhance 
system performance. 





DESCRIPTION 
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In a uniprocessing environment, the LOCK macro sets IPL to the IPL that 
corresponds to the constant IPL$_lockname. 


In a multiprocessing environment, the LOCK macro performs the following 
actions: 


¢ Preserves RO through the macro call (if preserve=YES is specified). 


¢ Generates a spin lock index of the form SPL$C_lockname and stores it 
in RO. 


¢ Calls SMP$ACQUIRE to obtain the specified spin lock. SMPSACQUIRE 
indexes into the system spin lock database (a pointer to which is located 
at SMP$AR_SPNLKVEC) to obtain the spin lock. Prior to securing 
the spin lock, SMP$ACQUIRE raises IPL to the IPL associated with the 


spin lock, determining the appropriate IPL from the spin lock structure 
(SPL$B_IPL). 
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In either processing environment, the LOCK macro performs the following 
tasks: 


e Preserves the current IPL at the specified location (if savipl is specified) 


e Sets the SMP-modified bit in the driver prologue table (DPT$V_ 
SMPMOD in DPT$L_FLAGS) 
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PURDPR 


Purges a UNIBUS adapter buffered data path. 





FORMAT PURDPR 


DESCRIPTION — The PURDPR macro calls IOC$PURGDATAP to purge a UNIBUS adapter 
buffered data path. A driver within an I/O subsystem configuration that 
does not provide buffered data paths may use the PURDPR macro because 
the purge operation detects memory parity errors that may have occurred 
during the transfer. When the PURDPR macro is invoked, R5 must contain 
the address of the UCB. 





When PURDPR returns control to its caller, the following registers contain the 
following values: 


Register Contents 

RO Status of the purge (success or failure) 

R1 Contents of data-path register, provided for the use of the driver's 
register dumping routine 

R2 Address of first map register, provided for the use of the driver's 
register dumping routine 

R3 Address of the CRB 
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READ_SYSTIME 


Reads the current system time. 





FORMAT READ_SYSTIME ast 





PARAMETER dst 


Quadword into which the macro inserts the system time. 





DESCRIPTION The READ_SYSTIME macro generates the code required to obtain a 
consistent copy of the system time from EXE$GQ_SYSTIME. 


Use of the READ_SYSTIME macro is subject to the following restrictions: 
e IPL must be less than 23. 
e The processor must be executing in kernel mode. 


e When using the macro within pageable program sections (or within code 
executing at IPL 2 and below), you must ensure that the pages involved 
are locked in memory. 





EXAMPLE 


READ_SYSTIME RO 


The READ_SYSTIME macro inserts the current system time in RO and R1. 
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RELALT 


Releases a set of Q22-bus alternate map registers allocated to the driver. 





FORMAT RELALT 





DESCRIPTION The RELALT macro calls IOC$RELALTMAP to release a set of Q22-bus 
alternate map registers (registers 496 to 8191) allocated to the driver. When 
the RELALT macro is invoked, R5 must contain the address of the UCB. 
RELALT destroys the contents of RO through R2. 
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RELCHAN 


RELCHAN 


Releases all controller data channels allocated to a device. 





FORMAT RELCHAN 





DESCRIPTION The RELCHAN macro calls IOC$RELCHAN to release all controller data 
channels allocated to a device. When the RELCHAN macro is invoked, R5 
must contain the address of the UCB. RELCHAN destroys the contents of RO 
through R2. 
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RELDPR 
RELDPR 

Releases a UNIBUS adapter data path register allocated to the driver. 
FORMAT RELDPR 





DESCRIPTION _ The RELDPR macro calls IOC$RELDATAP to release a UNIBUS adapter 
buffered data path allocated to the driver. 


When the RELDPR macro is invoked, R5 must contain the address of the 
UCB. RELDPR destroys the contents of RO through R2. 
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RELMPR 


RELMPR 


Releases a set of UNIBUS map registers or a set of the first 496 Q22-bus 
map registers allocated to the driver. 





FORMAT RELMPR 





DESCRIPTION — The RELMPR macro calls IOC$RELMAPREG to release a set of map registers 
allocated to the driver. When the RELMPR macro is invoked, R5 must contain 
the address of the UCB. RELMPR destroys the contents of RO through R2. 
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RELSCHAN 
RELSCHAN 

Releases all secondary channels allocated to the driver. 
FORMAT RELSCHAN 





DESCRIPTION — The RELSCHAN macro calls IOC$RELSCHAN to release all secondary data 
channels (for example, the MASSBUS adapter’s controller data channel) 
allocated to the driver. 


When the RELSCHAN macro is invoked, R5 must contain the address of the 
UCB. RELSCHAN destroys the contents of RO through R2. 
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REQALT 


REQALT 


Obtains a set of O22-bus alternate map registers. 





FORMAT REQALT 





DESCRIPTION _ The REQALT macro calls IOC$REQALTMAP to obtain a set of Q22-bus 
alternate map registers (registers 496 to 8191). When the REQALT macro is 
invoked, the following registers must contain the following values: 


Register Contents 
R5 Address of UCB 
OO(SP) Address of caller’s caller 


The REQALT macro destroys the contents of RO through R2. 
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REQCOM 


Invokes VMS device-independent I/O postprocessing. 





FORMAT REQCOM 





DESCRIPTION — The REQCOM macro calls IOC$REQCOM to complete the processing of an 
I/O request after the driver has finished its portion of the processing. 


When the REQCOM macro is invoked, the following registers must contain 
the following values: 


Register Contents 

RO First longword of I/O status 
R1 Second longword of I/O status 
R5 Address of UCB 


The REQCOM macro destroys the contents of RO through R3. All other 
registers are also destroyed if the action of the macro initiates the processing 
of a waiting I/O request for the device. 
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REQDPR 


REQDPR 


Requests a UNIBUS adapter buffered data path. 





FORMAT REQDPR 





DESCRIPTION — The REQDPR macro calls IOC$REQDATAP to request a UNIBUS adapter 
buffered data path. 


When the REQDPR macro is invoked, the following registers must contain 
the following values: 


Register Contents 
R5 Address of UCB 
OO(SP) Address of caller's caller 


The REQDPR macro destroys the contents of RO through R2. 
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REQMPR 


REQMPR 


Obtains a set of UNIBUS map registers or a set of the first 496 Q22 bus 
map registers. 





FORMAT REQMPR 





DESCRIPTION — The REQMPR macro calls IOC$REQMAPREG to obtain a set of map registers. 
When the REQMPR macro is invoked, the following registers must contain 
the following values: 


Register Contents 
R5 Address of UCB 
00(SP) Address of caller's caller 


The REQMPR macro destroys the contents of RO through R2. ~ 
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REQPCHAN 


Obtains a controller’s data channel. 





FORMAT 


REQPCHAN [pri] 





PARAMETERS [pri] 


Priority of request. If the priority is HIGH, REQPCHAN calls 
IOC$REQPCHANH,; otherwise it calls IOC$REQPCHANL. 





DESCRIPTION 


The REQPCHAN macro calls IOC6REQPCHANH or IOC$REQPCHANL, 
depending on the priority specified, to obtain a controller’s data channel. 


When the REQPCHAN macro is invoked, the following registers must contain 
the following values: 


Register Contents 
R5 Address of UCB 
OO(SP) Address of cailer’s caller 


The REQPCHAN macro returns the address of the device’s CSR in R4 and 
destroys the contents of RO through R2. 
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REQSCHAN 
REQSCHAN 

Obtains a secondary MASSBUS data channel. 
FORMAT REQSCHAN [pri] 





PARAMETER [pri] 
Priority of request. If the priority is HIGH, REQSCHAN calls 
IOC$REQSCHANH,; otherwise it calls IOC6REQSCHANL. 





DESCRIPTION — The REQSCHAN macro calls IOC$REQSCHANH or IOC$REQSCHANL, 
depending on the priority specified, to obtain a secondary MASSBUS data 
channel. 


When the REQSCHAN macro is invoked, the following registers must contain 
the following values: 


Register Contents 
R5 Address of UCB 
OO(SP) Address of caller’s caller 


The REQSCHAN macro returns the address of the device’s CSR in R4 and 
destroys the contents of RO through R2. 
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SAVIPL 


SAVIPL 


Saves the current IPL of the local processor. 





FORMAT SAVIPL [dst=-(SP)] 





PARAMETER [dst=—(SP)] 


Address of longword in which to save the current IPL. 





DESCRIPTION The SAVIPL macro stores the current IPL of the local processor, as recorded 
in the processor IPL register (PR$_IPL), in the specified location. 
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SETIPL 


Sets the current IPL of the local processor. 





FORMAT SETIPL [ip-31] [environ=MULTIPROCESSOR] 





PARAMETERS = [ipF31] 
Level at which to set the current IPL. The default value sets IPL to 31, 
blocking all interrupts on the local processor. 


[environ=MULTIPROCESSOR] 


Processing environment in which the SETIPL synchronization macro is 

to be assembled. If you do not specify environ, or if you do specify 
environ=-MULTIPROCESSOR, the SETIPL macro generates the following 
assembly-time warning message, where xx is an IPL above IPL 2: 


%MACRO-W-GENWARN, Generated WARNING: Raising IPL to #xx provides no multiprocessing synchronization 


If you are certain that the purpose of the macro invocation is to block only 
local processor events, you can disable the warning message by including 
environ=-UNIPROCESSOR in the invocation. 





DESCRIPTION _ The SETIPL macro sets the IPL of the local processor by moving the specified 
ipl or IPL 31 into its IPL register (PR$_IPL). 


Note that the SETIPL macro provides full synchronization only in a 
uniprocessing environment. In a multiprocessor configuration, SETIPL 

is suitable only for blocking events on the local processor. To provide 
synchronized access to system resources and devices in a multiprocessing 
environment, you must use the DEVICELOCK/DEVICEUNLOCK, 
FORKLOCK/FORKUNLOCK, and LOCK/UNLOCK macros. 
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SETIPL 





EXAMPLE 
DEVICELOCK - ;Secure device lock 
LOCKADDR=UCB$L_DLCK(R5),- ;(also raises IPL to device lock's IPL) 
_ SAVIPL=- (SP) ;Save current IPL on stack 
SETIPL #IPL$_POWER, - ;Raise IPL to 31 
ENVIRON=UNIPROCESSOR ;Avoid assembly-time warning 
BBC #UCB$V_POWER, - 
UCB$W_STS(R5) , 30$ ;If clear, no power failure 


;Service power failure 


DEVICEUNLOCK - ;Release device lock 


LOCKADDR=UCB$L_DLCK(R5) , - 
NEWIPL=(SP) + ;Restore old IPL from stack 
;Branch 


30$: ;Start device 


WF IKPCH ;Wait for interrupt 


Here, the DEVICELOCK macro achieves synchronized systemwide access 
to the device registers. The SETIPL macro then synchronizes the local 
processor against its own powerful interrupt event. The code does not need 
to synchronize systemwide against powerful events, because its interest is 
truly limited to the local processor. 


Note that the WFIKPCH macro conditionally releases the device lock and 
restores the old IPL prior to returning control to the caller’s caller. 
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SOFTINT 


Requests a software interrupt from the local processor at a specified IPL. 





FORMAT SOFTINT jp! 





PARAMETER ipl 


IPL at which the software interrupt is being requested. 





DESCRIPTION _ The SOFTINT macro moves the specified ipl into the local processor's 
Software Interrupt Request Register (PR$_SIRR), thus requesting a software 
interrupt at that IPL on the processor. 


The processor may take either of the following actions: 


e If the local processor is executing at an IPL below the level of the 
requested interrupt, it immediately transfers control to a software interrupt 
service routine for the appropriate IPL. 


e If the local processor is executing at an IPL equal or above the level of the 
requested interrupt, it does not transfer control to the software interrupt 
service routine until its IPL drops below the specified ipl. 


The SOFTINT macro does not provide the capability of requesting a software 
interrupt from another processor in a VMS multiprocessing environment. 
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TIMEWAIT 


Waits for a specified bit to be cleared or set within a specified length of 
time. 





FORMAT TIMEWAIT _ time ,bitval ,source ,context [, sense=. TRUE. ] 





PARAMETERS time 
Number of 10-microsecond intervals to wait. VMS multiplies this value 
by a processor-specific value in order to calculate the interval to wait. The 
processor-specific value is inversely proportional to the speed of the processor, 
but is never less than 1. 


bitval | 
Mask that determines which bits to test. 


source 
Address of bits to test. 


context 
Context in which the bits are to be tested (B, W, or L). 


[sense=. TRUE. ] 


If .TRUE., test for one or more of the specified bits set; otherwise test for all 
bits cleared. 





DESCRIPTION The TIMEWAIT macro checks for a specific state by testing bits for a specified 
length of time. 


If the state comes into existence during the specified interval, the TIMEWAIT 
macro places a success code in RO and returns control to its caller. If the state 
does not occur during the specified period, the TIMEWAIT macro places a 
failure code in RO and returns control to its caller. The TIMEWAIT macro 
destroys the contents of R1, and preserves the contents of all other registers. 


Because the TIMEDWAIT macro provides more flexibility and a more 
controlled environment for detection of events or conditions, DIGITAL 
recommends its use over the TIMEWAIT macro. 





EXAMPLE 
MoVva RO, - (SP) ;Save RO,R1 
TIMEWAIT #3,#RL_CS_M_CRDY, - 
RL_CS(R4) ,W 
MOVG (SP) +,RO ;Restore RO,R1 


DLDRIVER’s unit initialization routine uses the TIMEWAIT macro to wait 30 
microseconds for the RL11 controller to be ready before proceeding. 
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TIMEDWAIT 


TIMEDWAIT 


Waits a specified interval of time for an event or condition to occur. 





FORMAT 


TIMEDWAIT | time [,ins1] [,ins2] [,ins3] [,ins4] |,ins5] 
[,ins6] [,donelbl] [,imbedlbl] [,ublb!] 





PARAMETERS 


time 

Number of 10-microsecond intervals to wait. VMS multiplies this value 

by a processor-specific value in order to calculate the interval to wait. The 
processor-specific value is inversely proportional to the speed of the processor, 
but is never less than 1. 


If you do not specify any embedded instructions, increase the value of time 
by 25 percent. 


If you specify embedded instructions that take longer to execute than the 
average, such as the POLYD instruction, they will cause TIMEDWAIT to wait 
proportionally longer. 


[ins1] 


First instruction in the loop. 


[ins2] 


Second instruction in the loop. 


[ins3] 


Third instruction in the loop. 


[ins4] 


Fourth instruction in the loop. 


[ins5] 


Fifth instruction in the loop. 


[ins6] 


Sixth instruction in the loop. 


[donelbl] 
Label placed after the instruction at the end of the TIMEDWAIT loop; 


embedded instructions can pass control to this label in order to pass control 
to the instruction following the invocation of the TIMEDWAIT macro. 


[imbedlbl] 
Label placed at the first of the embedded instructions; after executing a 


processor-specific delay, the TIMEDWAIT macro passes control here to retest 
for the condition. 
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[ublbl] 


Label placed at the instruction that performs the processor-specific delay 
after each execution of the loop of embedded instructions; embedded 
instructions can pass control here in order to skip the execution of the rest of 
the embedded instructions in a given execution of the embedded loop. 








DESCRIPTION The TIMEDWAIT macro waits for a period of time for an event or condition 
to occur. You can specify up to six instructions for this macro to execute in a 
loop to determine whether the event has occurred. 

The TIMEDWAIT macro does not read the processor’s clock. The interval 
it waits is approximate and depends upon the processor and the set of 
instructions you choose for testing to see if the condition exists. 
TIMEDWAIT returns a status code (success or failure) in RO, destroys the 
contents of R1, and preserves all other registers. 

EXAMPLE 

TIMEDWAIT TIME=#600*«1000, - ;6-second wait loop 
INS1=<TSTB RL_CS(R4)>,- ;Is controller busy 
INS2=<BLSS 15$>,- ;If LSS - yes 
DONELBL=15$ ;Label to exit wait loop 

BLBC RO, 25$ ;Time expired - exit 


The unit initialization routine of DLDRIVER issues the TIMEDWAIT macro 
to wait a maximum of six seconds if another unit is busy on the controller’s 
channel. 
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UNLOCK 


UNLOCK 


Relinquishes synchronized access to a system resource as appropriate to 
the processing environment. 





FORMAT 


UNLOCK = lockname [,newipl] [, condition] [, preserve=YES] 





PARAMETERS 


lockname 
Name of the system resource to be released or restored. 


[newipl] 
Location containing the IPL to which to lower. A prior invocation of the 
LOCK macro may have stored this IPL value. 


[condition] 

Indication of a special use of the macro. The only defined condition 
is RESTORE, which causes the macro—in a VMS multiprocessing 
environment—to call SMP$RESTORE instead of SMP$RELEASE, thus 
releasing a single acquisition of the spin lock by the local processor. 


[preserve=YES] 

Indication that the macro should preserve RO across an invocation. If you do 
not need to retain the contents of RO, specifying preserve=NO can enhance 
system performance. 





DESCRIPTION 
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In a uniprocessing environment, the UNLOCK macro lowers IPL to newipl. 
If an interrupt is pending at the current IPL or at any IPL above newipl, the 
current procedure is immediately interrupted. 


In a multiprocessing environment, the UNLOCK macro performs the following 
tasks: 


e Preserves RO through the macro call (if preserve=YES is specified). 


¢ Generates a spin lock index of the format SPL$C_lockname and stores it 
in RO. 


¢ Calls SMP$RELEASE or, if condition=RESTORE is specified, 
SMP$RESTORE. These routines index into the system spin lock database 
(a pointer to which is located at SMP$AR—_SPNLKVEC) to release the 
appropriate spin lock. 


e Moves any specified newip] into the local processor’s IPL register (PR$_ 
IPL). If an interrupt is pending at the current IPL or at any IPL above 
newipl, the current procedure is immediately interrupted. 


In either processing environment, the UNLOCK macro sets the SMP-modified 
bit in the driver prologue table (DPT$V_SMPMOD in DPT$L_FLAGS). 
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Defines an entry in a port driver vector table within the context of a 
$VECINI macro. 





FORMAT 


$VEC entry, routine 





PARAMETERS 


entry 
Name of the vector table entry, specified without the PORT_ prefix. 


routine 
Name of the service routine within the driver that corresponds to the entry 
point. 





DESCRIPTION 


A terminal port driver uses the $VEC macro to validate and generate a 
vector table entry. A driver need not invoke the $VEC macro to associate a 
routine with each entry in the vector table. The $VECINI macro initializes all 
unspecified entry points with the address of the driver’s null entry point. 


To use the $VEC macro, the driver must include an invocation of the 
$TTYMACS definition macro (from SYS$LIBRARY:LIB.MLB). See the 
description of the $VECINI macro for an example of creating a port driver 
vector table. 
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$VECEND 


Ends the scope of the $VECINI macro, thereby completing the definition of 
a port driver vector table. 





FORMAT $VECEND [end] 





PARAMETER [end] 


Flag controlling the generation of the end of the vector table. This argument 
is generally omitted so that the $VECEND macro can generate the end of the 
vector table. Otherwise, the $VECEND macro does not generate the end of 
the table. 





DESCRIPTION _ A terminal port driver uses the $VECEND macro to generate the longword 
of zeros that terminates a port driver vector table initialized by the 
$VECINI and $VEC macros. It also positions the location counter at label 
drivername$VECEND, as defined by the $VECINI macro. 


To use the $VECEND macro, the driver must include an invocation of 

the $TTYMACS definition macro (from SYS$LIBRARY:LIB.MLB). See the 
descriptions of the $VECINI and $VEC macros for additional information on 
creating a port driver vector table. 
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SVECINI 


Begins the definition of a port vector table. 














FORMAT $VECINI  drivername, null_routine [, prefix=PORT_] 
PARAMETERS - drivername 
Prefix (usually two letters) of the driver name (for example, DZ). 
null_routine 
Address of the driver’s null entry point, usually specified in the format 
drivername$NULL. This address contains an RSB instruction. 
[_prefix=PORT_] 
Prefix to be added to the symbols defined in subsequent invocations of the 
$VEC macro. 
DESCRIPTION __ A terminal port driver uses the $VECINI macro to begin the definition of a 
. port vector table and initialize each table entry to point to the driver’s null 
entry point. The $VECINI macro generates the label drivername$VEC at the 
beginning of the table and drivername$VECEND at the end of the table. 
The $VEC macro defines valid entries within the port driver vector table 
specified by the invocation of the $VECINI macro, and the $VECEND macro 
ends the table’s definition. 
To use the $VECINI macro, the driver must include an invocation of the 
$TTYMACS definition macro (from SYS$LIBRARY:LIB.MLB). 
EXAMPLE 
$VECINI DZ32,DZ$NULL 
$VEC STARTIO,DZ32$STARTIO ;Start new output 
$VEC SET_LINE,DZ32$SET_LINE ;Set new parity/speed 
$VEC XON,DZ32$X0N ;Send XON 
$VEC XOFF ,DZ32$X0FF ;Send XOFF 
$VEC STOP,DZ32$STOP ;Stop current output 
$VEC ABORT ,DZ32$ABORT ;Abort current output 
$VEC RESUME,DZ32$RESUME ;Resume stopped output 
$VEC MAINT,DZ32$MAINT ;Invoke maintenance functions 
$VECEND 


In this example, the $VECINI macro creates a port driver vector table. The 
table entries defined by the eight subsequent invocations of the $VEC macro 
(PORT _STARTIO, PORT_SET_LINE, and so on) are set up to point to the 
specified routines in the port driver. The $VECINI macro initializes any entry 
point not defined by a $VEC macro (for instance, PORT_SET_MODEM) with 
the address of the null entry point, DZ$NULL. 


The $VECEND macro concludes the definition of the port driver vector table. 
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$VIELD, _VIELD 


Defines symbolic offsets and masks for bit fields. 





FORMAT { wits \ mod , inibit , fields 





PARAMETERS mod 
Module in which this bit field is defined; the prefix portion of the name of the 
symbol to be defined. 


inibit 
Bit within the field on which the positions of the bits to be defined are based. 


fields 


One or more fields of the form <sym,[size=1],[mask]> , where these 
arguments are defined as follows: 


Argument Meaning 

sym String appended to the string “mod$” to form the name of 
this bit field. 

[size=1] Size in bits of this bit field. If you specify a value greater than 
1, the VIELD macro generates a symbol for the size of the bit 
field. 

[mask] Character “M” if the VIELD macro is to generate a symbol for 


the mask of the bit field, blank otherwise. 





DESCRIPTION The $VIELD and —_VIELD macros define bit fields whose names have the 
form mod$x_sym and mod_x_sym (where x can be V, S, or M and sym is 
a value supplied in the fields argument). Because the dollar-sign character 
($) is reserved for use in VMS-defined symbols, use of the _VIELD macro is 
recommended for non-DIGITAL-supplied device drivers. 


See the descriptions of the $DEFINI and $EQULST macros for additional 
information on defining symbols for data structure fields. 
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SVIELD, _VIELD 





EXAMPLE 


$EQULST XA_K 


woth i s 


0,1,<- 


<fncti,2>- 
<fnct2,4>- 
<fnct3,8>- 
_VIELD XX_CSR,0,<- 
<GO, ,M>,- 
<FNCT,3,M>,- 
<XBA,2,M>,- 
<IE, ,M>,- 
<MAINT>, - 
<ATTIN>, - 


> 


;Define CSR bit values 


;Control/status register 


;Start device 
;Function bits 
;Extended address bits 
;Enable interrupts 
;Maintenance bit 


;Status from other processors 


XX_CSR_M_FNCT 
XX_CSR_M_GO 
XX_CSR_M_IE 
XX_CSR_M_XBA 
XX_CSR_S_FNCT 
XX_CSR_S_XBA 
XX_CSR_V_FNCT 
XX_CSR_V_GO 
XX_CSR_V_IE 
XX_CSR_V_MAINT 
XX_CSR_V_XBA 


noi t @ouw hb th tow ote ou 


This code excerpt produces the following symbols: 


OQOOOO00E 
00000001 
00000040 
00000030 
00000003 
00000002 
00000001 
00000000 
00000006 
00000007 
00000004 
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WFIKPCH, WFIRLCH 


Suspends a driver fork thread and folds its context into a fork block in 
anticipation of a device interrupt or timeout. When WFIKPCH is invoked, 
the fork thread keeps ownership of the controller channel while waiting; 
when WFIRLCH is invoked, the fork thread releases ownership of the 
controller channel. 











FORMAT WFIKPCH excpt [, time-65536] 
WFIRLCH 

PARAMETERS excpt 
Name of a device timeout handling routine; the address of this routine must 
be within 65,536 bytes of the address at which the WFIKPCH macro is 
invoked. 
[time=65536] 
Timeout interval, expressed as the number of seconds to wait for an interrupt 
before a device timeout is considered to exist. A value equal to or greater 
than 2 is required because the timeout detection mechanism is accurate only 
to within one second. 

DESCRIPTION The WFIKPCH and WFIRLCH macros push time on the stack and call 
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IOC$WFIKPCH and IOC$SWFIRLCH, respectively. After the JSB instruction 
that makes the routine call, either of these macros constructs a word that 
contains the relative offset to the timeout handling routine specified in 
excpt. Because these routines compute and store the address of the following 
instruction in the fork block at UCB$L_FPC, the software timer interrupt 
service routine can determine the routine’s location and call it if the device 
times out before it can deliver an interrupt. 


IOC$WFIKPCH and IOC$WFIRLCH assume that, prior to the invocation of 
the macro, a DEVICELOCK macro has been issued—both to synchronize with 
other device activity and to leave the IPL of the previous code thread on the 
top of the stack. Upon storing the context of and suspending the current code 
thread, IOC$WFIKPCH and IOC$WFIRLCH return control to their caller’s 
caller at the stored IPL. 


When the WFIKPCH or WFIRLCH macro is invoked, the following locations 
must contain the values listed: 


Location Contents 

R5 Address of UCB 

OO(SP) IPL at which control is passed to the caller’s caller 
04(SP) Address (in the caller's caller) at which to return control 
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The suspended code thread is resumed by the occurrence of an interrupt 
signaling the successful completion of a device operation. When an interrupt 
occurs, control returns to the instruction following the macro. If a device 
timeout occurs before an interrupt can be posted, the timeout handling 
routine specified in excpt is called. In both instances, subsequent code can 
assume that only R3 and R4 have been preserved across the suspension. 


See the descriptions of the DEVICELOCK, IOFORK, and SETIPL macros for 
examples of the use of the WFIKPCH macro. 


C Operating System Routines 


This appendix describes the VMS operating system routines that are used by 
device drivers and employs the following conventions: 


Most routines reside in modules within the [SYS] facility of VMS. A 
routine description provides a facility name (in brackets) only if the 
module is not located in the [SYS] facility. 


Many routines are not directly called by device drivers. Rather, VMS 
supplies macros that drivers invoke to accomplish the routine call. The 
description of a routine that has such a macro interface lists the name of 
the associated macro. Appendix B describes how a driver can use these 
macros. 


System routines generally return a status value in RO (for instance, SS$_ 
NORMAL). The low-order bit of this value indicates successful (1) or 
unsuccessful (0) completion of the routine. Additional information on 
returned status values appears in the VMS System Services Reference 
Manual and the VMS System Messages and Recovery Procedures Reference 
Volume. 


If a register is not used to transfer output or is not explicitly indicated as 
destroyed, a driver can assume that its contents are preserved. 
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COM$DELATTNAST 


Delivers all attention ASTs linked in the specified list. 





module COMDRVSUB 
input 
Location Contents 
R4 Address of listhead of AST control blocks 
R5 Address of UCB 
output 
Location Contents 
Specified listhead Empty 
RO through R11 Preserved 
synchronization © COM$DELATTNAST executes and exits at the caller's IPL, and acquires no 
spin locks. 
DESCRIPTION COM$DELATTNAST removes all AST control blocks (ACBs) from 


the specified list. Using each ACB as a fork block, it schedules a fork 
process at IPL$_QUEUEAST to queue the AST to its target process. 
COMS$DELATTNAST dequeues each ACB from the head of the list, 

thus removing them in the reverse order of their declaration by 
COMS$SETATTNAST. Note that in certain circumstances attention ASTs 

can be delivered to a user process before the delivery of I/O completion ASTs 
previously posted by the driver. 


Operating System Routines 





COMS$SDRVDEALMEM 
Deallocates system dynamic memory. 
module COMDRVSUB 
input 
Location Contents 
RO Address of block to be deallocated 
IRP$W_SIZE Size of block in bytes (must be at least 24 bytes 
long) 
output 
Location Contents 
RO through R11 Preserved 
synchronization _ Drivers can call COM$DRVDEALMEM from any IPL. COM$DRVDEALMEM 
executes at the caller’s IPL and returns control at that IPL. The caller retains 
any spin locks it held at the time of the call. 
DESCRIPTION §COM$DRVDEALMEM calls EXE$}DEANONPAGED to deallocate the buffer 


specified by RO. If the driver is running at an IPL above IPL$_SYNCH, 
COM$DRVDEALMEM transforms the block to be deallocated into a fork 
block, and requests a software interrupt at IPL$_.QUEUEAST. The code that 
executes in the fork process jumps to EXE${DEANONPAGED. 


If the buffer to be deallocated is less than FKB$C_LENGTH in size, or its 
address is not aligned on a 16-byte boundary, COM$DRVDEALMEM issues a 
BADDALRQSZ bugcheck. 


Operating System Routines 


COM$FLUSHATTNS 


COM$FLUSHATTNS 


Flushes an attention AST list. 


module COMDRVSUB 


input 


Location 

R4 

R5 

R6 

R7 

UCB$L_DLCK 
PCB$L_PID 
PCBSW_ASTCNT 


output 


Location 

RO 

Ri, R2, R7 
PCBS$W_ASTCNT 


Specified listhead 


Contents 

Address of PCB 

Address of UCB 

Number of the assigned I/O channel 
Address of listhead of AST control blocks 
Address of device lock 

Process ID 

ASTs remaining in quota 


Contents 
SS$_NORMAL 
Destroyed 


Incremented by the number of AST control 
blocks that are flushed 


Updated 


synchronization COM$FLUSHATTNS raises IPL to device IPL, acquiring the corresponding 
device lock. Before returning control to its caller at the caller’s IPL, 
COM$FLUSHATTNS releases the device lock. The caller retains any spin 


locks it held at the time of the call. 





DESCRIPTION A driver's cancel-I/O routine calls COM$FLUSHATTNS to flush an attention 
AST list. A driver FDT routine calls COM$FLUSHATTNS to service a $QIO 
request that specifies a set-attention-AST function and a value of 0 in the p1 
argument. 


COM$FLUSHATTNS locates all AST control blocks whose channel number 
and PID match those supplied as input to the routine. It removes them from 
the specified list, deallocates them, and returns control to its caller. 


Operating System Routines 
COMS$POST 


COMS$POST 


Initiates device-independent postprocessing of an |/O request independent 
of the status of the device unit. 


module COMDRVSUB 
input 
Location Contents 
R3 Address of IRP 
R5 Address of UCB 
IRP$L_MEDIA Data to be copied to the |/O status block 
IRP$L_MEDIA+4. Data to be copied to the I/O status block 
output 
Location Contents 
RO and R1 Destroyed 
UCB$L_OPCNT Incremented 


synchronization _ Drivers call COM$POST at or above fork IPL. COM$POST executes at its 
caller’s IPL and returns control at that IPL. The caller retains any spin locks it 
held at the time of the call. 





DESCRIPTION _ A driver fork process calls COM$POST after it has completed device- 
dependent I/O processing for an I/O request initiated by EXESALTQUEPKT. 


COM$POST inserts the IRP into the local processor’s I/O postprocessing 
queue headed by CPU$L_PSBL, requests an IPL$_IOPOST software 
interrupt, and returns control to its caller. Unlike IOCS$IOPOST, it does 
not attempt to dequeue any IRP waiting for the device or change the busy 
status of the device. 


Operating System Routines 


COMS$SETATTNAST 


COMS$SETATTNAST 


Enables or disables attention ASTs. 





module COMDRVSUB 
input 
Location Contents 
R3 Address of IRP 
R4 Address of current PCB 
R5 Address of UCB 
R7 Address of listhead of AST control blocks 
AP Address of $QIO system service argument list 
IRP$W_CHAN 1/O request channel index number 
UCB$L—DLCK Address of device lock 
PCBSW_ASTCNT Number of ASTs remaining in process quota 
PCB$L_PID Process ID 
OO(AP) Address of process’s AST routine 
O4(AP) AST parameter 
O8(AP) Access mode for AST 
output 
Location Contents 
RO SS$_NORMAL, SS$_EXQUOTA, or 
SS$_INSFMEM 
R1 and R2 Destroyed 
R3 Address of IRP 
R5 Address of UCB 
R6, R7, R8 Destroyed 
PCBSW_ASTCNT Decremented 
Specified listhead Updated 
synchronization © COM$SETATTNAST raises IPL to device IPL, acquiring the corresponding 
device lock. It returns control to its caller at the caller’s IPL. 
A driver FDT routine calls COM$SETATTNAST to service a $QIO request 


DESCRIPTION 


that specifies a set-attention-AST function. 


If the pl argument of the request contains a zero, COM$SETATTNAST 
transfers control to COM$FLUSHATTNS, which disables all ASTs indicated 
by the PID and I/O channel number (IRP$W_CHAN). COM$FLUSHATTNS 
searches through the AST control block (ACB) list, extracts each identified 
ACB, deallocates, and returns to the caller of COM$SETATTNAST. 


Operating System Routines 
COM$SETATTNAST 


If the p1 argument of the request contains the address of an AST routine, 
COM$SETATTNAST decrements PCB§6W_ASTCNT and allocates an 
expanded AST control block (ACB) that contains the following information: 


e¢ Spin lock index SPL$6C_QUEUEAST 
e Address of the AST routine (as specified in p1) 
e AST parameter (as specified in p2) 


e¢ Access mode (as specified in p3 and maximized against the current 
process’s access mode and bit ACB$V_QUOTA set to indicate a process- 
requested AST) 


¢ Number of the assigned I/O channel 


e PID of the requesting process 


COMS$SETATTNAST links the ACB to the start of the specified linked list 
of ACBs located in a UCB extension area. (See Section A.14 for information 
on defining an extension to a UCB.) COM$DELATTNAST can later use the 
expanded ACB to fork to IPL$_QUEUEAST, at which IPL it reformats the 
block into a standard ACB. 


If the process exceeds buffered I/O or AST quotas, or if there is no memory 
available to allocate the expanded ACB, COM$SETATTNAST restores 
PCB$W_ASTCNT to its original value and transfers control to EXE$ABORTIO 
with error status. 


Operating System Routines 


ERL$DEVICERR, ERL$DEVICTMO, ERL$DEVICEATTN 


ERLSDEVICERR, ERL$DEVICTMO, 


ERLSDEVICEATTN 


Allocate an error message buffer and record in it information concerning 


the error. 
module ERRORLOG 


input 
Location 


R5 
DDT$W_ERRORBUF 
UCB$L_DEVCHAR 
UCB$W_FUNC 
UCBS$L _IRP 


UCB$L_ORB 


output 


Location 
UCB$W_ERRCNT 
UCB$L_EMB 
UCB$L_STS 

RO through R11 


Contents 

Address of UCB 

Size of error message buffer in bytes 
Bit DEV$V_ELG set 

Bit IO$V_INHERLOG clear 


Address of IRP currently being processed 
(ERLSDEVICERR and ERLSDEVICTMO only) 


ORB address 


Contents 

Incremented 

Address of error message buffer 
UCB$V_ERLOGIP set 


Preserved 


synchronization A driver calls ERL$DEVICERR, ERL$DEVICTMO, or ERL$DEVICEATTN, 
at or above fork IPL, holding the corresponding fork lock in a VMS 
multiprocessing environment. These routines return control to the caller 
at the caller’s IPL. The caller retains any spin locks it held at the time of the 


call. 





DESCRIPTION — ERL$DEVICERR and ERL$DEVICTMO log an error associated with a 
particular I/O request. ERLGDEVICEATTN logs an error that is not associated 
with an I/O request. Each of these routines performs the following steps: 


e Increments UCB$W_ERRCNT to record a device error. If the error-log- 
in-progress bit (UCB$V_ERLOGIP in UCB$L STS) is set, the routine 
returns control to its caller. 


e  Allocates from the current error log allocation buffer an error message 
buffer of the length specified in the device’s DDT (in argument erlgbf to 
the DDTAB macro). This allocation is performed at IPL$_EMB holding 


the EMB spin lock. 


Operating System Routines 
ERL$DEVICERR, ERL$DEVICTMO, ERL$DEVICEATTN 


¢ Initializes the buffer with the current system time, error log sequence 
number, and error type code. These routines use the following error type 


codes: 

ERL$DEVICERR Device error (EMB$C_DE) 
ERL$DEVICTMO Device timeout (EMB$C_DT) 
ERL$DEVICEATTN Device attention (EMB$C_DA) 


e Places the address of the error message buffer in UCB$L_EMB. 
e Sets UCB$V_ERLOGIP in UCB$L_STS. 


e Loads fields from the UCB, the IRP, and the DDB into the buffer, 
including the following: 


UCB$B_DEVCLASS Device class 


UCB$B_DEVTYPE Device type 

IRP$L_PID Process ID of the process originating the |/O request 
(ERL$_DEVICERR and ERL$_DEVICTMO) 

iIRP$W_BOFF Transfer parameter (ERLSDEVICERR and 
ERL$DEVICTMO) 

IRP$W_BCNT Transfer parameter (ERLSDEVICERR and 
ERL$DEVICTMO) 

UCB$L_MEDIA Disk size 

UCBSW_UNIT Unit number 

UCBSW_ERRCNT Count of device errors 

UCB$L_OPCNT Count of completed operations 

ORB$L_OWNER UIC of volume owner 

UCB$L_DEVCHAR Device characteristics 

UCB$B_SLAVE Slave unit number 

IRP$W_FUNC I/O function value (ERLSDEVICERR and 
ERL$DEVICTMO) 

DDB$ST_NAME Device name (concatenated with cluster node name 


if appropriate) 


¢ Loads into RO the address of the location in the buffer in which the 
contents of the device registers are to be stored. 


¢ Calls the driver’s register dumping routine, the address of which is 
specified in the regdmp argument to the DDTAB macro. 


Note that a driver must define the local disk UCB extension or local tape UCB 
extension, as described in Section A.14, to use these error logging routines. 


Operating System Routines 


EXESABORTIO 


EXESABORTIO 


Completes the servicing of an 1/O request without returning status to the 
1/O status block specified in the request. 





module SYSQIOREQ 
input 
Location Contents 
RO First longword of status for the I/O status block 
R3 Address of IRP 
R4 Address of current PCB 
R5 Address of UCB 
IRP$L_IOSB Address of |/O status block 
IRP$B_RMOD ACB$V_QUOTA set indicates process-specified 
AST pending 
PCBS$W_ASTCNT Count of available AST queue entries 
output 
Location Contents 
IRP$L_IOSB Zero 
IRP$B_RMOD ACB$V_QUOTA clear 
PCB$W_ASTCNT Incremented if ACB$V_QUOTA was set 
synchronization EXE$ABORTIO executes at its caller’s IPL and raises to fork IPL, acquiring the 
associated fork lock in a VMS multiprocessing environment. As a result, its 
caller cannot be executing above fork IPL. A driver usually transfers control 
to EXE$ABORTIO at IPL$_ASTDEL. 
EXE$ABORTIO exits at normal process IPL (IPL 0). 
DESCRIPTION — EXE$ABORTIO performs the following actions: 
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1 Clears IRP$L_IOSB so that no status is returned by I/O postprocessing 


2 Clears ACB$V_QUOTA in IRP$B_RMOD to prevent the delivery of any 
AST to the process specified in the I/O request 


3 Updates the count of available AST entries at PCB$W_ASTCNT, if 


necessary 


4 Inserts the IRP in the local processor’s I/O postprocessing queue headed 


by CPU$L_PSBL 


5 If the queue is empty, requests a software interrupt from the local 
processor at IPL$¢_IOPOST 


This interrupt causes I/O postprocessing to occur before the remaining 
instructions in EXESABORTIO are executed. 


Operating System Routines 
EXESABORTIO 


When all I/O postprocessing has been completed, EXESABORTIO regains 
control and completes the I/O operation as follows: 


© Lowers IPL to zero 


e Issues the RET instruction that restores the original access mode of the 
caller of the $QIO system service and returns control to the system service 
dispatcher 


EXE$ABORTIO returns in RO the final status code saved when the exit routine 


was called. Any ASTs specified when the I/O request was issued will not be 
delivered, and any event flags requested will not be set. 
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Operating System Routines 
EXE$ALLOCBUF, EXE$ALLOCIRP 


EXESALLOCBUF, EXESALLOCIRP 


Allocates a buffer from nonpaged pool for a buffered-1/O operation. 





module MEMORYALC 
input 
Location Contents 
R1 Size of requested buffer in bytes 
(EXESALLOCBUF only). This value should include 
the 12 bytes required to store header information. 
PCB$L_STS PCB$V_SSRWAIT clear if the process should 
wait if no memory is available for requested 
buffer; set if resource wait mode is disabled. 
output 
Location Contents 
RO SS$_NORMAL or SS$_INSFMEM. 
R1 Size of requested buffer in bytes (IRP$C_LENGTH 
for EXE$ALLOCIRP). 
R2 Address of allocated buffer. 
R4 See the following discussion. 
IRP$W_SIZE (in allocated Size of requested buffer in bytes (for 
buffer) EXE$ALLOCBUF), IRP$C_LENGTH (for 
EXE$ALLOCIRP). 
IRPS$B_TYPE (in allocated DYN$C_BUFIO (for EXE$ALLOCBUF), DYN$C_. 
buffer) IRP (for EXESALLOCIRP). 
synchronization | EXE$ALLOCBUF and EXE$ALLOCIRP set IPL to IPL$_ASTDEL. As a result 
they cannot be called by code executing above IPL$_ASTDEL. They return 
control to their callers at the caller’s IPL. 
DESCRIPTION — EXE$ALLOCBUF attempts to allocate a buffer of the requested size from 
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nonpaged pool; EXESALLOCIRP attempts to allocate an IRP from nonpaged 


pool. 


If sufficient memory is not available, EXES;ALLOCBUF and EXES$ALLOCIRP 
move the current PCB (CTL$GL_PCB) into R4 to determine whether the 
process has resource wait mode enabled. If PCB$V_SSRWAIT in PCB$L_— 
STS is clear, these routines place the process in a resource wait state until 


memory is released. 


The caller must check and adjust process quotas (JIB$L_BYTCNT 

and/or JIB$L_BYTLM) by calling EXE$DEBIT_BYTCNT or EXE$DEBIT_ 
BYTCNT_BYTLM. (Note that you can perform this task and allocate a 
buffer of the requested size by using the routines EXE$DEBIT_BYTCNT_ 
ALO and EXE$DEBIT_BYTCNT_BYTLM_ALO. These routines invoke 


EXE$ALLOCBUF.) 


Operating System Routines 
EXE$ALLOCBUF, EXE$ALLOCIRP 


The normal buffered I/O postprocessing routine (IOC$REQCOM), initiated 
by the REQCOM macro, readjusts quotas and also deallocates the buffer. 


Note that the value returned in R1 and placed at IRPS$W_SIZE in the 
allocated buffer is the size of the requested buffer. The actual size of 

the allocated buffer is determined according to the algorithms used by 
EXE$ALONONPAGED and the size of the lookaside list packets. The 
nonpaged pool deallocation routine (EXES[DEANONPAGED), called in 
buffered I/O postprocessing, uses similar algorithms when returning memory 
to nonpaged pool. 
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Operating System Routines 
EXE$ALONONPAGED 


EXES$ALONONPAGED 


Allocates a block of memory from nonpaged pool. 





module MEMORYALC 
input 

Location Contents 

R1 Size of requested block in bytes 

output 

Location Contents 

RO SS$_NORMAL or SS$_INSFMEM. 

R1 If the allocation succeeds from one of the 
lookaside lists, the value returned in R1 remains 
the size of the requested block. If the allocated 
block is from general nonpaged pool, the value in 
R1 is the requested size, rounded up to a 16-byte 
multiple. 

R2 Address of allocated block. 

synchronization EXE$ALONONPAGED executes at its caller’s IPL and at IPL$_POOL, 
obtaining the POOL spin lock in a VMS multiprocessing environment. For 
this reason, it cannot be called by code executing above IPL$_POOL. 

EXE$ALONONPAGED returns control to its caller at the caller’s IPL. The 

caller retains any spin locks it held at the time of the call. 

DESCRIPTION _ Depending upon the size of the requested block, EXESALONONPAGED 
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allocates nonpaged pool either from one of the lookaside lists (SRP, IRP, or 
LRP) or from the variable region of nonpaged dynamic memory. 


EXE$ALONONPAGED does not initialize the header of the allocated block of 
memory. 


Operating System Routines 
EXES$ALONPAGVAR 


EXESALONPAGVAR 


module 


input 


output 


synchronization 


Allocates a block of memory from the variable region of nonpaged pool. 


MEMORYALC 


Location Contents 
R1 Size of requested block in bytes 


Location Contents 
RO SS$_NORMAL or SS$_INSFMEM 


R1 Size of requested buffer, rounded up to a 16-byte 
multiple 


R2 Address of allocated block 


EXE$ALONPAGVAR executes at its caller’s IPL and at IPL$_POOL, holding 
the POOL spin lock in a VMS multiprocessing environment. For this reason, 
its caller cannot be executing at an IPL above IPL$_POOL. 


EXE$ALONPAGVAR returns control to its caller at the caller’s IPL. The caller 
retains any spin locks it held at the time of the call. 





DESCRIPTION 


EXE$ALONPAGVAR allocates a block of memory of the requested 

size from the variable region of nonpaged dynamic memory. Because 
EXE$ALONPAGVAR does not attempt to service the request from the 
lookaside lists, it is suitable for driver fork processes that may afterwards 
return the allocated block to nonpaged pool in pieces. 


EXE$ALONPAGVAR does not initialize the header of the allocated block of 
memory. 
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Operating System Routines 
EXE$ALOPHYCNTG 


EXESALOPHYCNTG 


module 


input 


output 


synchronization 


Allocates a physically-contiguous block of memory. 


MEMORYALC 


Location Contents 
R1 Number of physically contiguous pages to allocate 


Location Contents 


RO SS$_NORMAL, SS$_INSFMEM, or SS$_ 
INSFSPTS 


R2 System virtual address of allocated block, if the 
allocation succeeds 


EXE$ALOPHYCNTG raises IPL to IPL$_SYNCH and obtains the MMG 
spin lock. As a result, its caller cannot be executing above IPL$_SYNCH 
or hold any spin lock ranked higher than MMG. (For instance, a driver fork 
process executing at IPL$_SYNCH holding the IOLOCK8 fork lock can call 
EXE$ALOPHYCNTG.) 


EXE$ALOPHYCNTG returns control to its caller at the caller’s IPL. The caller 
retains any spin lock it held at the time of the call. 





DESCRIPTION 
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EXE$ALOPHYCNTG allocates a physically contiguous block of memory. You 
cannot deallocate memory allocated by EXESALOPHYCNTG. 


Note that the number of SPT slots available depends on the value of the 
SPTREQ system parameter. 


Operating System Routines 
EXESALTQUEPKT 


EXESALTQUEPKT 


Delivers an IRP to a driver's alternate start-|/O routine without regard for 
the status of the device. 


module SYSQIOREQ 
input 
Location Contents 
R3 Address of IRP 
R5 Address of UCB 
DDT$L_ALTSTART Address of alternate start-I/O routine 
UCB$B_FLCK Fork lock index 
UCB$L_DDB Address of unit’s DDB 
DDB$L_DDT Address of DDT 
output 
Location Contents 
RO through R5 Destroyed 


synchronization A driver FDT routine calls EXE$ALTQUEPKT at IPL$_ASTDEL. 
EXE$ALTQUEPKT raises to fork IPL (acquiring any required fork lock) 
before calling the driver’s alternate start-I[/O routine. When the alternate 
start-I/O routine returns control to it, EXESALTQUEPKT returns control to its 
caller at the caller’s IPL (having released its acquisition of the fork lock). 





DESCRIPTION — EXE$ALTQUEPKT calls the driver’s alternate start-I/O routine. It does not 
test whether the unit is busy before making the call. 
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Operating System Routines 


EXE$CREDIT_BYTCNT, EXE$CREDIT_BYTCNT_BYTLM 


EXE$CREDIT_BYTCNT, 


EXE$CREDIT_BYTCNT_BYTLM 


Return credit to a job’s buffered-I/O byte count quota and byte limit. 





module EXSUBROUT 
input 
Location Contents 
RO Number of bytes to return to the byte count 
quota (and byte limit) 
R4 Address of current PCB 
JIBSB_FLAGS JIB$V_BYTCNT_WAITERS set if there are 
processes waiting for byte count quota from this 
JIB . 
JIB$L_BYTCNT Job’s byte count usage quota 
JIB$L_BYTLM Job’s byte limit (used by EXESCREDIT_BYTCNT_ 
BYTLM) 
output 
Location Contents 
RO Destroyed 
JIBSL_BYTCNT Updated 
JIBSL_BYTLM Updated (by EXESCREDIT_BY TCNT_BYTLM) 
synchronization | EXE$CREDIT_BYTCNT and EXE$CREDIT_BYTCNT_BYTLM raise IPL to 
IPL$_SYNCH and obtain the JIB spin lock and the SCHED spin lock (if 
JIB$6V_BYTCNT_WAITERS is set) in a VMS multiprocessing environment. As 
a result, their callers cannot be executing above IPL$_SYNCH or hold any 
spin lock ranked higher than JIB. (For instance, a driver fork process executing 
at IPL$_SYNCH holding the IOLOCKS8 fork lock can call these routines. It 
cannot, however, hold the SCHED spin lock.) 
EXE$CREDIT_BYTCNT and EXE$CREDIT_BYTCNT_BYTLM return control 
to their callers at the caller’s IPL. Their caller retains any spin locks it held at 
the time of the call. 
DESCRIPTION — EXE$CREDIT_BYTCNT provides a synchronized method of crediting a job’s 
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byte count quota to JIB$|L_BYTCNT. EXE$CREDIT_BYTCNT_BYTLM also 
credits a job’s byte limit to JIB$L_BYTLM. 


Both routines round the value specified in RO up to the nearest 16-byte 
boundary before applying it to the JIB. Both check JIB6V_BYTCNT_WAITERS 
to determine if any process is waiting for the return of nonpaged pool quota 
for this JIB. If a process is waiting, EXE$CREDIT_BYTCNT calls a system 
routine that attempts to fill any pending requests. 


Operating System Routines 
EXE$DEANONPAGED 


EXES$DEANONPAGED 


module 


input 


output 


synchronization 


Deallocates a block of memory and returns it to nonpaged pool. 


MEMORYALC 


Location Contents 
RO Address of block to be deallocated 
IRP$W_SIZE Size of block in bytes 


Location Contents 
R1 and R2 Destroyed 


EXE$DEANONPAGED executes at the caller’s IPL, at IPL$_SYNCH 
holding the SCHED spin lock, and at IPL$_POOL holding the POOL 
spin lock. As a result, its caller cannot be executing above IPL$_SYNCH. 
EXE$DEANONPAGED returns control to its caller at the caller’s IPL. The 
caller retains any spin locks it held at the time of the call. 





DESCRIPTION 


EXE$DEANONPAGED deallocates the specified block of memory to 
nonpaged dynamic memory, returning it to a lookaside list or the variable 
region of nonpaged pool as appropriate. It also reports to the scheduler the 
availability of the deallocated pool. 


EXE$DEANONPAGED issues a BADDALRQSZ bugcheck if the address of 
the pool to be deallocated is not aligned on a 16-byte boundary. 
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Operating System Routines 


EXE$DEBIT_BYTCNT(_NW), EXE$DEBIT_BYTCNT_BYTLM(_NW) 


EXE$DEBIT_BYTCNT(_NW), 
EXE$DEBIT_BYTCNT_BYTLM(_NW) 


module 


input 


output 


synchronization 
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Determine whether a job’s buffered |/O byte count quota usage permits 
the process to be granted additional buffered I/O and, if so, adjust the 
job’s byte count quota and byte limit. 


EXSUBROUT 


Location 
R1 


R4 
PCB$L_STS 


lOC$GW_MAXBUF 


JIB$L_BYTCNT 
JIB$L_BYTLM 


Location 

RO 

R1 
JIB$L_BYTCNT 
JIB$L_BYTLM 


Contents 


Number of bytes to be deducted; bit 31, 
when set, disables the routine’s check against 
lIOC$GW_MAXBUF 


Address of current PCB 


PCB$V_SSRWAIT clear if the process should 
wait for buffered-I|/O byte quota; set if resource 
wait mode is disabled 


Maximum number of buffered I/O bytes the 
system allows to a single request 


Job’s byte count usage quota 


Job’s byte limit (used by EXESDEBIT_BYTCNT_ 
BYTLM and EXE$DEBIT_BYTCNT_BYTLM_NW) 


Contents 

SS$_NORMAL or SS$_EXQUOTA 
Number of bytes deducted; bit 31 cleared 
Updated if successful 


Updated if successful (by EXE$DEBIT_BYTCNT_ 
BYTLM and EXE$DEBIT_BYTCNT_BYTLM_NW) 


EXE$DEBIT_BYTCNT, EXE$DEBIT_BYTCNT_NW, EXE$DEBIT_BYTCNT_ 
BYTLM, and EXE$DEBIT_BYTCNT_BYTLM_NW raise IPL to IPL$_SYNCH 
and obtain the JIB spin lock in a VMS multiprocessing environment. As a 
result, their callers cannot be executing above IPL$_SYNCH or hold any spin 
lock ranked higher than JIB. (For instance, a driver fork process executing 

at IPL$_SYNCH holding the IOLOCKS8 fork lock can call these routines. It 
cannot, however, hold the SCHED spin lock.) 


EXE$DEBIT_BYTCNT, EXE$DEBIT_BYTCNT_NW, EXE$DEBIT_BYTCNT_ 


-BYTLM, and EXE$DEBIT_BYTCNT_BYTLM_NW return control to their 


callers at the caller’s IPL. The caller retains any spin locks it held at the time 


of the call. 


Operating System Routines 


EXESDEBIT_BYTCNT(_NW), EXESDEBIT_BYTCNT_BYTLM(_NW) 





DESCRIPTION 


EXE$DEBIT_BYTCNT and EXE$DEBIT_BYTCNT_NW check whether a 
process has sufficient quota for a buffer of the specified size and, if so, 
deduct the corresponding number of bytes from the job’s byte count quota. 
EXE$DEBIT_BYTCNT_BYTLM and EXE$DEBIT_BYTCNT_BYTLM_NW also 
adjust the job’s byte limit. All routines round the value specified in R1 up to 
the nearest 16-byte boundary before applying it to the JIB. 


If the process’s quota usage is too large, EXES/DEBIT_BYTCNT and 
EXE$DEBIT_BYTCNT_BYTLM place the process into a resource wait state, 
based on the setting of PCB$V_SSRWAIT, until sufficient quota is returned 
to the job. EXE$DEBIT_BYTCNT_NW and EXE$DEBIT_BYTCNT_BYTLM_ 
NW do not refer to PCB$V_SSRWAIT and return an error if the process has 
exceeded its job’s quota. These latter routines never wait for sufficient quota. 


If bit 31 in R1 is clear, all routines compare the byte count in R1 against 
IOC$GW_MAXBUF, returning an error if the system’s maximum buffer 
allotment to a process is exceeded. 


Operating System Routines 
EXE$DEBIT_BYTCNT_ALO, EXE$DEBIT_BYTCNT_BYTLM_ALO 


EXE$DEBIT_BYTCNT_ALO, 


EXE$DEBIT_BYTCNT_BYTLM_ALO 


module 


input 


output 


synchronization 
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Determine whether a job’s buffered I/O byte count quota usage permits 
the process to be granted additional buffered |/O and, if so, allocates the 
requested amount of nonpaged pool and adjust the job’s byte count quota 


and byte limit. 


EXSUBROUT 


Location 
R1 


R4 
PCB$L_STS 


lOC$GW_MAXBUF 


JIB$L_BYTCNT 
JIB$L_BYTLM 


Location 

RO 

R1 

R2 

R3 
JIB$L_BYTCNT 
JIBSL_BYTLM 


IRP$W_SIZE (in allocated 
buffer) 


IRP$B_TYPE (in allocated 
buffer) 


Contents 


Number of bytes to be allocated (including the 
12 bytes required for the buffer’s header) and 
deducted; bit 31, when set, disables the routine’s 
check against IOC6GW_MAXBUF 


Address of current PCB 


PCB$V_SSRWAIT clear if the process should 
wait for buffered-|/O byte quota; set if resource 
wait mode is disabled 


Maximum number of buffered 1/O bytes the 
system allows to a single request 


Job’s byte count usage quota 


Job's byte limit (used by EXE$DEBIT_BYTCNT_ 
BYTLM_ALO) 


Contents 

SS$_NORMAL or SS$_EXQUOTA 
Number of bytes deducted; bit 31 cleared 
Address of requested buffer 

Destroyed 

Updated if successful 


Updated if successful (by EXE$DEBIT_BYTCNT_ 
BYTLM_ALO) 


Size of requested buffer in bytes 


DYN$C_BUFIO 


EXE$DEBIT_BYTCNT_ALO and EXE$DEBIT_BYTCNT_BYTLM_ALO raise 
IPL to IPL$¢_SYNCH and obtain the JIB spin lock in a VMS multiprocessing 
environment. As a result, their callers cannot be executing above IPL$_ 
SYNCH or hold any spin lock ranked higher than JIB. (For instance, a driver 
fork process executing at IPL$_SYNCH holding the IOLOCK8 fork lock can 
call these routines. It cannot, however, hold the SCHED spin lock.) 


Operating System Routines 
EXE$DEBIT_BYTCNT_ALO, EXE$DEBIT_BYTCNT_BYTLM_ALO 


EXE$DEBIT_BYTCNT_ALO and EXE$DEBIT_BYTCNT_BYTLM_ALO return 
control to their callers at the caller’s IPL. The caller retains any spin locks it 
held at the time of the call. 





DESCRIPTION — EXE$DEBIT_BYTCNT_ALO checks whether a process has sufficient quota for 
a buffer of the specified size and, if so, allocates the buffer from nonpaged 
pool and deducts the corresponding number of bytes from the job’s byte 
count quota. EXE$DEBIT_BYTCNT_BYTLM_ALO also adjusts the job’s byte 
limit. Both routines round the value specified in R1 up to the nearest 16-byte 
boundary before applying it to the JIB. 


If the process’s quota usage is too large, EXE$}DEBIT_BYTCNT_ALO and 
EXE$DEBIT_BYTCNT_BYTLM_ALO place the process into a resource wait 
state, based on the setting of PCB$V_SSRWAIT, until sufficient quota is 
returned to the job. 


If bit 31 in R1 is clear, these routines compare the byte count in R1 against 
IOC$GW_MAXBUF, returning an error if the system’s maximum buffer 
allotment to a process is exceeded. 
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Operating System Routines 
EXE$FINISHIO, EXE$FINISHIOC 


EXESFINISHIO, EXESFINISHIOC 


Complete the servicing of an !/O request and return status to the I/O 
status block specified in the request. 


module SYSQIOREQ 
input 
Location Contents 
RO First longword of status for the I/O status block 
R1 Second longword of status for the |/O status 
block (EXESFINISHIO only) 
R3 Address of IRP 
R4 Address of current PCB 
R5 Address of UCB 
output 
Location Contents 
RO SS$_NORMAL 
IRP$L_IOST 1 First longword of !/O status 
IRP$L_IOST2 Second longword of |/O status (cleared by 
EXES$FINISHIOC) 
UCB$L_OPCNT Incremented 


synchronization | EXE$FINISHIO and EXE$FINISHIOC execute at their caller’s IPL and raise 
to fork IPL, acquiring the associated fork lock in a VMS multiprocessing 
environment. As a result, their callers cannot be executing above fork IPL. A 
driver usually transfers control to these routines at IPL$_ASTDEL. 


EXE$FINISHIO and EXE$FINISHIOC exit at IPL 0 (normal process IPL). 





DESCRIPTION — EXE$FINISHIOC clears the contents of R1. Then, EXE$FINISHIO or 
EXE$FINISHIOC takes the following steps to complete the processing of 
the I/O request: 


e Increases the number of I/O operations completed on the current device 
in the operation count field of the UCB (UCB$L_OPCNT). This task 
is performed at fork IPL, holding the associated fork lock in a VMS 
multiprocessing environment. 


e Stores the contents of RO and R1 in the IRP. 


e Inserts the IRP in the local processor’s I/O postprocessing queue headed 
by CPU$L_PSBL. 


e If the queue is empty, requests a software interrupt from the local 
processor at IPL$_IOPOST. 
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Operating System Routines 
EXESFINISHIO, EXE$FINISHIOC 


This interrupt causes postprocessing to occur before the remaining instructions 
in EXE$FINISHIO or EXE$FINISHIOC are executed. 


When all I/O postprocessing has been completed, EXE$FINISHIO or 
EXE$FINISHIOC regains control and completes the I/O operation as follows: 


e Places status SS$._NORMAL in RO 
e Lowers IPL to zero 


e Issues the RET instruction that restores the original access mode of the 
caller of the $QIO system service and returns control to the system service 
dispatcher 


The image that issued the $QIO receives SS$_NORMAL status in RO, 


indicating that the I/O request has completed without device-independent 
error. 
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EXESFORK 


EXESFORK 


Creates a fork process on the local processor. 





module FORKCNTRL 
macro FORK 
input 
Location Contents 
R5 Address of fork block 
OO(SP) Return PC of caller 
04(SP) Return PC of caller’s caller 
FKB$B_FLCK Fork lock index or fork IPL 
output 
Location Contents 
R3 Destroyed 
R4 Fork IPL 
FKB$L_FR3 (UCB$L_FR3) R3 of caller 
FKB$L_FR4 (UCB$L_FR4) R4 of caller 
FKB$L_FPC (UCB$L__FPC) OO(SP) 
synchronization EXE$FORK acquires no spin locks and leaves IPL unchanged. It returns 
control to its caller’s caller. 
DESCRIPTION _ EXE$FORK saves the contents of R3 and R4 (in FKB$L_FR3 and FKB$L— 
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FR4, respectively) in the fork block specified by R5, and pops the return PC 
value from the top of the stack into FKB$L_—FPC. 


If FKB$B_FLCK contains a fork lock index, EXE$FORK determines the fork 
IPL by using this value as an index into the spin lock IPL vector (SGMP$AR_ 
IPLVEC). EXE$FORK inserts the fork block into the fork queue on the local 
processor (headed by CPU$Q_—SWIQFL) corresponding to this IPL. If the 
queue is empty, EXE$FORK issues a SOFTINT macro, requesting a software 
interrupt from the local processor at that fork IPL. 


Unlike EXE$IOFORK, EXE$FORK does not disable timeouts by clearing 
UCB$V_TIM in the UCB$L_STS field. 


Operating System Routines 
EXESINSERTIRP 


EXESINSERTIRP 


Inserts an IRP into the specified queue of IRPs according to the base 
priority of the process that issued the I/O request. 





module SYSQIOREQ 
input 
Location Contents 
R2 Address of 1/O queue listhead for the device 
R3 Address of IRP 
IRP$B_PRI Base priority of process requesting the !/O 
output 
Location Contents 
R1 Destroyed 
PSL <2> (Z bit) Set if the entry is first in the queue, cleared if at 
least one entry is already in the queue 
Pending-|/O queue IRP inserted 
synchronization | EXE$INSERTIRP must be called at fork IPL or higher. In a VMS 
multiprocessing environment, the caller must also hold the associated fork 
lock. EXE$INSERTIRP does not alter IPL or acquire any spin locks. It returns 
to its caller. 
DESCRIPTION _ EXES$INSERTIRP determines the position of the specified IRP in the pending- 


I/O queue according to two factors: 


e Priority of the IRP, which is derived from the requesting process’s base 
priority as stored in the IRP$B_PRI 


e Time that the entry is queued; for each priority, the queue is ordered on a 
first-in/first-out basis 


EXE$INSERTIRP inserts the IRP into the queue at that position, adjusts the 
queue links, and sets the Z bit in the PSL to indicate the status of the queue. 
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EXESINSIOQ, EXESINSIOQC 


EXESINSIOQ, EXESINSIOQC 


Insert an IRP in a device's pending-|/O queue and call the driver's start-I/O 
routine if the device is not busy. 
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module SYSQIOREQ 
input 
Location Contents 
R3 Address of IRP 
R5 Address of UCB 
UCB$B_FLCK Fork lock index 
UCB$L_STS UCB$V_BSY set indicates device is busy, clear 
indicates device is idle 
UCB$L_IOQFL Address of pending-|/O queue listhead 
UCB$W_OLEN Length of pending-I/O queue 
output 
Location Contents 
RO, R1, R2 Destroyed. Other registers (used by the driver's 
start-I/O routine) are destroyed if the start-I/O 
routine is called. 
UCB$L_STS UCB$V_BSY set. 
UCB$W_QLEN incremented. 
synchronization EXE$INSIOQ and EXE$INSIOQC immediately raise to fork IPL and, in a 
VMS multiprocessing environment, obtain the corresponding fork lock. As a 
result, their callers must not be executing at an IPL higher than fork IPL or 
hold a spin lock ranked higher than the fork lock. 
EXE$INSIOQ unconditionally releases ownership of the fork lock before 
returning control to the caller without possession of the fork lock. If a fork 
process must retain possession of the fork lock, it should call EXESINSIOQC 
instead. 
‘DESCRIPTION — EXES$INSIOQ and EXE$INSIOQC increment UCB$W_QLEN and proceed 


according to the status of the device (as indicated by UCB$V_BSY in UCBSW_ 


STS) as follows: 


e If the device is busy, call EXES$INSERTIRP to place the IRP on the 
device’s pending-I/O queue. 


e If the device is idle, call IOCSINITIATE to begin device processing of the 
I/O request immediately. IOC$INITIATE transfers control to the driver’s 


start-I/O routine. 


Operating System Routines 
EXESINSTIMO. 


EXESINSTIMO 


Inserts a timer queue element (TQE) into the timer queue. 





module EXSUBROUT 
input 
Location Contents 
RO, R1 Quadword expiration time for TOE 
R5 Address of TQE to be inserted 
EXE$GO _1ST_TIME Expiration time of first TOE in timer queue 
output 
Location Contents 
R2, R3 Destroyed 
TOESQ_TIME Quadword expiration time for TOE 
EXE$GO_1ST_TIME Updated if TOE is inserted at the head of the 
timer queue 
synchronization EXE$INSTIMQ immediately raises to IPL$_TIMER (IPL$_SYNCH), obtaining 
the TIMER spin lock in a VMS multiprocessing environment. As a result, its 
caller must not be executing above IPL$_SYNCH or hold any spin locks of a 
higher rank. (For instance, a driver fork process executing at IPL$_SYNCH 
holding the IOLOCK8 fork lock can call EXESINSTIMQ.) 
EXE$INSTIMOQ returns control to its caller at the caller’s IPL. The caller 
retains any spin locks it held at the time of the call. 
DESCRIPTION _ EXES$INSTIMQ inserts the specified TQE into the timer queue according to 


its expiration time. If the expiration time of the new TQE is sooner than that 
of the first TQE in the queue, EXE$INSTIMQ raises IPL to interval clock IPL 
(obtaining the HWCLK spin lock in a VMS multiprocessing environment), 
inserts it on the head of the queue, and updates EXE$GQ _1ST_TIME. 


C-—29 


Operating System Routines 


EXES$IOFORK 


EXESIOFORK 


Creates a fork process on the local processor for a device driver, disabling 
timeouts from the associated device. 





module FORKCNTRL 
macro IOFORK 
input 
Location Contents 
R5 Address of fork block (usually the UCB) 
OO(SP) Return PC of caller 
04(SP) Return PC of caller's caller 
FKB$B_FLCK (UCB$B_FLCK) Fork lock index or fork IPL 
output 
Location Contents 
R3 Destroyed 
R4 Fork IPL 
UCB$L_STS UCB$V_TIM cleared, disabling device timeouts 
FKB$L_FR3 (UCB$L_FR3) R3 of caller 
FKB$L_FR4 (UCB$L_FR4) R4 of caller 
FKB$L_FPC (UCB$L_FPC) OO(SP) 
synchronization —EXE$IOFORK acquires no spin locks and leaves IPL unchanged. It returns 
control to its caller’s caller. 
DESCRIPTION _ EXES$IOFORK first disables timeouts from the target device by clearing 
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UCB$V_TIM in UCB$L_STS. 


It saves the contents of R3 and R4 (in FKB$L_FR3 and FKB$L_FR4, 
respectively) in the fork block specified by R5, and pops the return PC 
value from the top of the stack into FKB$L_FPC. 


If FKB$B_FLCK contains a fork lock index, EXE$IOFORK determines the fork 
IPL by using this value as an index into the spin lock IPL vector (SMP$AR— 
IPLVEC). EXE$IOFORK inserts the fork block into the fork queue on the 
local processor (headed by CPU$Q_SWIQFL) corresponding to this IPL. If 
the queue is empty, EXESIOFORK issues a SOFTINT macro, requesting a 
software interrupt from the local processor at that fork IPL. 


EXES$MODIFY 


Operating System Routines 


EXESMODIFY 


Translates a logical read or write function into a physical read or write 
function, transfers $Q1O0 system service parameters to the IRP, validates 
and prepares a user buffer, and proceeds with or aborts a direct-|/O, DMA 


read/write operation. 





module SYSQIOFDT 
input 

Location Contents 

R3 Address of IRP. 

R4 Address of current PCB. 

R5 Address of UCB. 

R6 Address of CCB. 

R7 Bit number of the 1/O function code. 

R8 Address of FDT entry for this routine. 

OO(AP) Virtual address of buffer (p1). 

O4(AP)} Number of bytes in transfer (p2.) The maximum 
number of bytes that EXESMODIFY can transfer 
is 65,535 (128 pages minus one byte). 

12(AP) Carriage control byte (p4). 

IRP$W_FUNC 1/O function code. 

output 

Location Contents 

RO, R1, R2 Destroyed 

IRP$L_IOST2 p4 

IRP$W._STS IRP$V_FUNC set, indicating a read function 

IRP$W_FUNC Logical read or write function code converted to 
physical function 

IRP$L_SVAPTE System virtual address of the process page-table 
entry (PTE) that maps the first page of the buffer 

IRP$W_BOFF Byte offset to start of transfer in page 

IRP$L_BCNT Size of transfer in bytes 

synchronization | EXE$MODIFY is called as a driver FDT routine at IPL$_ASTDEL. 
DESCRIPTION __ A driver uses EXE$MODIFY as an FDT routine when the driver must both 


read from and write to the user-specified buffer. Because EXES}MODIFY 
transfers control to EXES$QIODRVPKT if its operations are successful or 
EXE$ABORTIO if they are not, it must be the last FDT routine called to 
perform the preprocessing of I/O read/write requests. A driver cannot use 
EXE$MODIFY for buffered I/O operations. 
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EXESMODIFY 


EXE$MODIFY performs the following functions: 
e Sets IRP$V_FUNC in IRP$W_STS to indicate a read function. 


e Writes the p4 argument of the $QIO request into IRP$L_IOST2 (IRP$B_ 
CARCON). 


e Translates logical read and write functions to physical read and write 
functions. 


e Examines the size of the transfer, as specified in the p2 argument of the 
$QIO request, and takes one of the following actions: 


— If the transfer byte count is zero, EXE$MODIFY transfers control to 
EXE$QIODRVPKT to deliver the IRP to the driver’s start-I/O routine. 
The driver start-I/O routine should check for zero-length buffers to 
avoid mapping them to UNIBUS, Q22-bus, MASSBUS, or VAXBI 
node space. An attempted mapping can cause a system failure. 


— If the byte count is not zero, EXESMODIFY loads the byte count and 
the starting address of the transfer into R1 and RO, respectively, and 
calls EXESMODIFYLOCK. 


EXE$MODIFYLOCK calls EXESMODIFYLOCKR. EXE$MODIFYLOCKR calls 
EXE$READCHKR, which performs the following tasks: 


¢ Moves the transfer byte count into IRP$6L_BCNT. If the byte count is 
negative, it returns SS$¢_BADPARAM status to EXE$MODIFYLOCKR. 


¢ Determines if the specified buffer is write accessible for a read I/O 
function, with one of the following results: 


— If the buffer allows write access, EXE$READCHKR sets IRP$V_FUNC 
in IRP$W_STS and returns SS$_NORMAL to EXE$SMODIFYLOCKR. 


— If the buffer does not allow write access, EXE$SREADCHKR returns 
SS$_ACCVIO status to EXE$MODIFYLOCKR. 


If EXES$READCHKR succeeds, EXES$MODIFYLOCKR moves into IRP$W_ 
BOFF the byte offset to the start of the buffer and calls MMG$IOLOCK. 
MMG$IOLOCK attempts to lock into memory those pages that contain the 
buffer, with one of the following results:! 


e If MMG$IOLOCK succeeds, EXES}MODIFYLOCKR stores in IRP$L— 
SVAPTE the system virtual address of the process PTE that maps the first 
page of the buffer, and returns control to EXES}MODIFY. EXE$MODIFY 
calls EXES$QIODRVPKT to deliver the IRP to the driver’s start-I/O 
routine. 


e If MMGSIOLOCK fails, it returns SS$_ACCVIO, SS$_INSFWSL, or page 
fault status to EXES}MODIFYLOCKR. 


" For read requests, MMG$IOLOCK performs an optimization for any nonvalid page contained within the buffer. 
It creates a demand-zero page rather than fault into memory the requested page. However, if the buffer 
extends to more than one page, this optimization is not possible. 
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EXESMODIFY 


If either EXESREADCHKR or MMGS$IOLOCK returns an error status other 
than a page fault condition, EXES}(MODIFYLOCKR calls EXES$ABORTIO. In 
the event of a page fault, EXES}{MODIFYLOCKR adjusts direct I/O count and 
AST count to the values they held before the I/O request, deallocates the 
IRP, and restarts the I/O request at the $QIO system service. This procedure 
is carried out so that the user process can receive ASTs while it waits for 
the page fault to complete. Once the page is faulted into memory, the $QIO 
system service will resubmit the I/O request. 
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EXE$MODIFYLOCK, EXE$MODIFYLOCKR 


EXES$MODIFYLOCK, EXESMODIFYLOCKR 


Validate and prepare a user buffer for a direct-I/O, DMA read/write 
operation. 





module SYSQIOFDT 
input 
Location Contents 
RO Virtual address of buffer 
R1 Number of bytes in transfer 
R3 Address of IRP 
R4 Address of current PCB 
R5 Address of UCB 
R6 Address of CCB 
R7 Bit number of the |/O function code 
output 
Location Contents 
RO SS$_NORMAL 
R1 System virtual address of the process page-table 
entry (PTE) that maps the first page of the buffer 
R2 1, indicating a read function 
IRP$W_STS IRP$V_FUNC set, indicating a read function 
IRP$L_SVAPTE System virtual address of the PTE that maps the 
first page of the buffer 
IRP$W_BOFF Byte offset to start of transfer in page 
IRP$L_BCNT Size of transfer in bytes 
synchronization |= EXE$MODIFYLOCK and EXE$MODIFYLOCKR are called by a driver FDT 
routine at IPL$_ASTDEL. 
A driver typically calls EXESMODIFYLOCKR instead of EXES|MODIFYLOCK 


DESCRIPTION 
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when it must lock multiple areas into memory for a single I/O request and 
must regain control, if the request is to be aborted, to unlock these areas. 

A driver uses either of these routines when it must both read and write to 
the user-specified buffer and it is not desirable to automatically deliver the 
IRP to the device unit after the buffer has been successfully locked. A driver 
cannot use EXE$MODIFYLOCK or EXE$MODIFYLOCKR for buffered I/O 
operations. 


Operating System Routines 
EXE$MODIFYLOCK, EXESMODIFYLOCKR 


EXE$MODIFYLOCK calls EXES{MODIFYLOCKR. 


EXE$MODIFYLOCKR calls EXESREADCHKR, which performs the following 
tasks: 


¢ Moves the transfer byte count into IRP$L_BCNT. If the byte count is 
negative, it returns SS$_BADPARAM status to EXE}MODIFYLOCKR. 


e Determines if the specified buffer is write accessible for a read I/O 
function, with one of the following results: 


— If the buffer allows write access, EXE$/READCHKR sets IRP$V_FUNC 
in IRP$W_STS and returns SS$_NORMAL to EXE$MODIFYLOCKR. 


— If the buffer does not allow write access, EXE$READCHKR returns 
SS$_ACCVIO status to EXE$MODIFYLOCKR. 


If EXE$SREADCHKR succeeds, EXES$MODIFYLOCKR moves into IRP$W_ 
BOFF the byte offset to the start of the buffer and calls MMG$IOLOCK, 
disabling a paging mechanism used in write-only operations. MMG$IOLOCK 
attempts to lock into memory those pages that contain the buffer, with one of 
the following results:? 


e If MMG$IOLOCK succeeds, EXESMODIFYLOCKR stores in IRP$L— 
SVAPTE the system virtual address of the process PTE that maps the first 
page of the buffer, and returns success status to its caller. 


e If MMG$IOLOCK fails, it returns SS$¢_ACCVIO, SS$_INSFWSL, or page 
fault status to EXE$MODIFYLOCKR. 


If the initial call was to EXE$MODIFYLOCK and either EXE$;READCHKR 

or MMGS$IOLOCK returns an error status other than a page fault condition, 
EXE$MODIFYLOCKR calls EXES$ABORTIO. In the event of a page fault, 
EXE$MODIFYLOCKR adjusts direct I/O count and AST count to the values 
they held before the I/O request, deallocates the IRP, and restarts the 1/O 
request at the $QIO system service. This procedure is carried out so that the 
user process can receive ASTs while it waits for the page fault to complete. 
Once the page is faulted into memory, the $QIO system service will resubmit 
the I/O request. 


If the initial call was to EXES{MODIFYLOCKR and an error occurs, 
EXE$MODIFYLOCKR, by means of a coroutine call, returns control to the 
driver’s FDT routine with status in RO. The driver performs whatever device- 
specific actions are required to abort the request, preserving the contents of 
RO and R1. When the driver issues the RSB instruction, control is returned to 
EXE$MODIFYLOCKR. EXE$MODIFYLOCKR proceeds to abort or resubmit 
the I/O request. 


Otherwise, these routines return success status to their callers. 


* For read requests, MMG$IOLOCK performs an optimization for any nonvalid page contained within the buffer. 
It creates a demand-zero page rather than fault into memory the requested page. However, if the buffer 
extends to more than one page, this optimization is not possible. 
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A driver FDT routine that calls EXES{(MODIFYLOCKR must distinguish 
between successful and unsuccessful status when it resumes, as shown in the 
following example: 


JSB G*EXE$MODIFYLOCKR 
BLBS BUF_LOCK_OK 
BUF_LOCK_FAIL: 
; clean up this $QIO bookkeeping 


RSB 
BUF _LOCK_OK: 


;continue processing this I/0 request 


Operating System Routines 
EXESONEPARM 


EXESONEPARM 


Copies a single $010 parameter into the IRP and delivers the IRP to a 
driver's start-I/O routine. 


module SYSQIOFDT 
input 
Location Contents 
R3 Address of IRP 
R4 Address of current PCB 
R5 Address of UCB 
R6 Address of CCB 
R7 Bit number of the I/O function code 
R8 Address of FDT entry for this routine 
OO(AP) Address of first function-dependent parameter of 
the $QlO request (p1) 
output 
Location Contents 
IRP$L_MEDIA p1 


synchronization | EXE$ONEPARM is called as a driver FDT routine at IPL$_ASTDEL. 





DESCRIPTION EXE$ONEPARM processes an I/O function code that requires only one 
parameter. This parameter should need no checking: for instance, for read or 
write accessibility. EXESONEPARM stores the parameter, found at 00(AP), in 
IRP$L_MEDIA and transfers control to EXE$QIODRVPKT to deliver the IRP 
to the driver. 


Operating System Routines 
EXESQIODRVPKT 


EXESQIODRVPKT 


Delivers an IRP to the driver's start-|/O routine or pending-I/O queue, 
returns success status in RO, lowers IPL to O, and returns to the system 


service dispatcher. 





module SYSQIOREQ 
input 
Location Contents 
R3 Address of IRP 
R4 Address of current PCB 
R5 Address of UCB 
UCB$B_FLCK Fork lock index or fork IPL 
UCB$L_STS UCB$V_BSY set if device is busy, clear if device 
is idle 
UCB$L_IOQFL Address of pending-!/O queue listhead 
UCB$W_OLEN Length of pending-I/O queue 
output 
UCB$L_STS UCB$V_BSY set 
UCB$W_OLEN Incremented 
synchronization EXE$QIODRVPKT is called by a driver’s FDT routine at IPL6_ASTDEL. It 
exits at IPL 0 (normal process IPL). 
DESCRIPTION EXE$QIODRVPKT calls EXE$INSIOQ. EXE$INSIOQ checks the status of the 
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device and calls either EXE$INSERTIRP or IOC$INITIATE to place the IRP in 
the device’s pending-I/O queue or deliver it to the driver’s start-I/O routine, © 


respectively. 


When EXE$INSIOQ returns to EXE$QIODRVPKT at IPL$_ASTDEL, 
EXE$QIODRVPKT returns control to the system service dispatcher in the 


following steps: 
1 Loads SS$_NORMAL into RO 
2 Lowers IPL to zero 


3 Issues the RET instruction that restores the original access mode of the 
caller of the $QIO system service and returns control to the system service 
dispatcher 


The image that requested the I/O operation receives status SS$_NORMAL in 
RO, indicating that the I/O request has completed without device-independent 
error. 


Operating System Routines 
EXESQIORETURN 


EXESQIORETURN 


module 


input 


output 


synchronization 


Sets a success status code in RO, lowers IPL to O, and returns to the 
system service dispatcher. 


SYSQIOREQ 

Location Contents 

R5 Address of UCB 
UCB$B_FLCK Fork lock index or fork IPL 
Location Contents 

RO ~ SS$_NORMAL 


EXE$QIORETURN is typically called by a driver FDT routine at IPL$_ 
ASTDEL. Its caller cannot be executing above fork IPL or hold any spin locks 
other than the appropriate fork lock. 


EXE$QIORETURN releases any fork lock held by its caller before it issues the 
RET instruction. 





DESCRIPTION 


EXE$QIORETURN performs the following actions: 
¢ Loads SS$_NORMAL into RO 
¢ Lowers IPL to zero 


e Issues the RET instruction that restores the original access mode of the 
caller of the $QIO system service and returns control to the system service 
dispatcher 


The image that requested the I/O operation receives status SS$_NORMAL in 


RO, indicating that the I/O request has completed without device-independent 
error, 
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EXESREAD 


EXE$READ 


Translates a logical read function into a physical read function, transfers 
$QlO system service parameters to the IRP, validates and prepares a 
user buffer, and proceeds with or aborts a direct-I/O, DMA read/write 
operation. 





module SYSQIOFDT 
input 
Location Contents 
R3 Address of IFRP. 
R4 Address of current PCB. 
R5 Address of UCB. 
R6 Address of CCB. 
R7 Bit number of the I/O function code. 
R8 . Address of FDT entry for this routine. 
OO(AP) Virtual address of buffer (p1). 
O4(AP) Number of bytes in transfer (p2). The maximum 
number of bytes that EXESREAD can transfer is 
65,535 (128 pages minus one byte). 
12(AP) Carriage control byte (p4). 
IRP$W_FUNC 1/O function code. 
output 
Location Contents 
RO, R1, R2 Destroyed 
IRP$B_IOST2 p4 
IRP$W_STS IRP$V_FUNC set, indicating a read function 
IRP$W__FUNC Logical read function code converted to physical 
IRP$L_SVAPTE System virtual address of the process page-table 
entry (PTE) that maps the first page of the buffer 
IRP$W__BOFF Byte offset to start of transfer in page 
IRP$L_BCNT Size of transfer in bytes 
synchronization —EXE$READ is called as a driver FDT routine at IPL$_ASTDEL. 
DESCRIPTION A driver uses EXE$READ as an FDT routine when the driver must write 
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to the user-specified buffer. Because EXE$READ transfers control to 
EXE$QIODRVPKT if its operations are successful or EXESABORTIO if they 
are not, it must be the last FDT routine called to perform the preprocessing 
of read 1/O requests. A driver cannot use EXE$READ for buffered-I/O 
operations. 


Operating System Routines 
EXE$READ 


EXE$READ performs the following functions: 
¢ Sets IRP$V_FUNC in IRP$W_STS to indicate a read function 


e Writes the p4 argument of the $QIO request into IRP$L_IOST2 (IRP$B_ 
CARCON). 


¢ Translates a logical read function to a physical read function. 


e Examines the size of the transfer, as specified in the p2 argument of the 
$QIO request, and takes one of the following actions: 


— If the transfer byte count is zero, EXE$READ transfers control to 
EXE$QIODRVPKT to deliver the IRP to the driver’s start-I/O routine. 
The driver start-I/O routine should check for zero-length buffers to 
avoid mapping them to UNIBUS, Q22-bus, MASSBUS, or VAXBI 
node space. An attempted mapping can cause a system failure. 


— If the byte count is not zero, EXESREAD loads the byte count and the 
starting address of the transfer into R1 and RO, respectively, and calls 
EXE$READLOCK. 


EXE$READLOCK calls EXESREADLOCKR. 


EXE$READLOCKR calls EXES6READCHKR, which performs the following 
tasks: 


¢ Moves the transfer byte count into IRP$L_BCNT. If the byte count is 
negative, it returns SS$_BADPARAM status to EXESREADLOCKR. 


e Determines whether the specified buffer is write accessible for a read I/O 
function, with one of the following results: 


— If the buffer allows write access, EXESREADCHKR sets IRP$V_FUNC 
in IRP$W_STS, and returns SS$¢_NORMAL to EXE$READLOCKR. 


— If the buffer does not allow write access, EXE$READCHKR returns 
SS$_ACCVIO status to EXE$/READLOCKR. 


If EXES/READCHKR succeeds, EXES/READLOCKR moves into IRP$W_ 
BOFF the byte offset to the start of the buffer and calls MMG$IOLOCK. 
MMGSIOLOCK attempts to lock into memory those pages that contain the 
buffer, with one of the following results:? 


e If MMG$IOLOCK succeeds, EXESREADLOCKR stores in IRP$L_SVAPTE 
the system virtual address of the process PTE that maps the first page of 
the buffer, and returns control to EXE$READ. EXE$READ transfers 
control to EXE$QIODRVPKT to deliver the IRP to the driver’s start-I/O 
routine. 


¢ If MMG$IOLOCK fails, it returns SS$_ACCVIO, SS$_INSEWSL, or page 
fault status to EXES/READLOCKR. 


> For read requests, MMG$IOLOCK performs an optimization for any nonvalid page contained within the buffer. 
It creates a demand-zero page rather than fault into memory the requested page. However, if the buffer 
extends to more than one page, this optimization is not possible. 
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If either EXESREADCHKR or MMGS$IOLOCK returns an error status 

other than a page fault condition, EXESREADLOCKR transfers control to 
EXE$ABORTIO. In the event of a page fault, EXESREADLOCKR adjusts 
direct I/O count and AST count to the values they held before the I/O 
request, deallocates the IRP, and restarts the I/O request at the $QIO system 
service. This procedure is carried out so that the user process can receive 
ASTs while it waits for the page fault to complete. Once the page is faulted 
into memory, the $QIO system service will resubmit the I/O request. 


Operating System Routines 
EXE$READCHK, EXESREADCHKR 


EXESREADCHK, EXESREADCHKR 


Verify that a process has write access to the pages in the buffer specified 
in a $Ol0 request. 





module SYSQIOFDT 
input 
Location Contents 
RO Virtual address of buffer 
R1 Size of transfer in bytes 
R3 Address of IRP 
output 
Location Contents 
RO Virtual address of buffer (EXESREADCHK), SS$_ 
NORMAL (EXE$READCHKR), or error status 
R1 Size of transfer in bytes 
R2 1, indicating a read function 
R3 Address of IRP 
IRP$W_STS IRP$V_FUNC set, indicating a read function 
IRP$L_BCNT Size of transfer in bytes 
synchronization EXE$READCHK and EXE$READCHKR are called by a driver FDT routine at 
IPL$_ASTDEL. 
DESCRIPTION A driver uses either of these routines to check the write accessibility of a 


user-specified buffer. A driver typically calls EXES}READCHKR instead of 
EXE$READCHK when it must regain control before the request is aborted in 
the event the buffer is inaccessible. 


EXE$READCHK calls EXE$READCHKR. 
EXE$READCHKR performs the following tasks: 


¢ Moves the transfer byte count into IRP$L_BCNT. If the byte count is 
negative, it returns SS$_BADPARAM status to its caller. 


¢ Determines whether the specified buffer is write accessible for a read I/O 
function, with one of the following results: 


— If the buffer allows write access, EXE$/READCHKR sets IRP$V_FUNC 
in IRP$W_STS and returns SS$¢_NORMAL to its caller. 


—. If the buffer does not allow write access, EXESREADCHKR returns 
SS$_ACCVIO status to its caller. 
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If the initial call was to EXESREADCHK, and EXE$READCHKR returns error 
status, EXE$READCHK transfers control to EXES$ABORTIO to terminate the 
I/O request. If the initial call was to EXES{READCHKR, and an error occurs, 
EXE$READCHKR returns control to the driver. Otherwise, these routines 
return success status to their callers. 


A driver FDT routine that calls EXESREADCHKR must distinguish between 
successful and unsuccessful status when it resumes, as shown in the following 
example: 


JSB G*EXE$READCHKR 

BLBS BUF_ACCESS_OK 
BUF_ACCESS_FAIL: 
; clean up this $QI0 bookkeeping 


JSB G"EXE$ABORTIO 
BUF_ACCESS_OK: 


;continue processing this I/0 request 


Operating System Routines 
EXE$READLOCK, EXE$READLOCKR 


EXESREADLOCK, EXESREADLOCKR 


Validate and prepare a user buffer for a direct-|/O, DMA read operation. 





module SYSQIOFDT 
input 
Location Contents 
RO Virtual address of buffer 
R1 Number of bytes in transfer 
R3 Address of IRP 
R4 Address of current PCB 
R5 Address of UCB 
R6 Address of CCB 
R7 Bit number of the 1/O function code 
output 
Location Contents 
RO SS$_NORMAL 
R1 System virtual address of the process page-table 
entry (PTE) that maps the first page of the buffer 
R2 1, indicating a read function 
IRP$W_STS IRP$V_FUNC set, indicating a read function 
IRP$L_SVAPTE System virtual address of the PTE that maps the 
first page of the buffer 
IRP$W_BOFF Byte offset to start of transfer in page 
IRP$L_BCNT Size of transfer in bytes 
synchronization | EXE$READLOCK and EXE$READLOCKR are called by a driver FDT routine 
at IPL$_ASTDEL. 
DESCRIPTION A driver typically calls EXE$READLOCKR instead of EXE$READLOCK 


when it must lock multiple areas into memory for a single I/O request and 
must regain control, if the request is to be aborted, to unlock these areas. A 
driver uses either of these routines when it must write to the user-specified 
buffer and it is not desirable to automatically deliver the IRP to the device 
unit after the buffer has been successfully locked. A driver cannot use 
EXE$READLOCK or EXESREADLOCKR for buffered I/O operations. 


EXE$READLOCK calls EXES6READLOCKR. 


EXE$READLOCKR calls EXESREADCHKR, which performs the following 
tasks: 


¢ Moves the transfer byte count into IRP$L _BCNT. If the byte count is 
negative, it returns SS$_BADPARAM status to EXES$READLOCKR. 
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e Determines whether the specified buffer is write accessible for a read I/O 
function, with one of the following results: 


— If the buffer allows write access, EXESREADCHKR sets IRP$V_FUNC 
in IRP$W_STS and returns SS$_NORMAL to EXE$READLOCKR. 


— If the buffer does not allow write access, EXES/READCHKR returns 
SS$_ACCVIO status to EXES$SREADLOCKR. 


If EXESREADCHKR succeeds, EXESREADLOCKR moves into IRP$W_ 
BOFF the byte offset to the start of the buffer and calls MMG$IOLOCK. 
MMG$IOLOCK attempts to lock into memory those pages that contain the 
buffer, with one of the following results:4 


e If MMG$IOLOCK succeeds, EXE$SREADLOCKR stores in IRP$L_SVAPTE 
the system virtual address of the process PTE that maps the first page of 
the buffer, and returns success status to its caller. 


e If MMG$IOLOCK fails, it returns SS$_ACCVIO, SS$_INSFWSL, or page 
fault status to EXESREADLOCKR. 


If the initial call was to EXESREADLOCK and either EXESREADCHKR or 
MMGS$IOLOCK returns an error status other than a page fault condition, 
EXE$READLOCKR transfers control to EXESABORTIO. In the event of a 
page fault, EXESREADLOCKR adjusts direct I/O count and AST count to 
the values they held before the I/O request, deallocates the IRP, and restarts 
the I/O request at the $QIO system service. This procedure is carried out 
so that the user process can receive ASTs while it waits for the page fault to 
complete. Once the page is faulted into memory, the $QIO system service 
will resubmit the I/O request. 


If the initial call was to EXESREADLOCKR and an error occurs, 
EXE$READLOCKR, by means of a coroutine call, returns control to the 
driver’s FDT routine with status in RO. The driver performs whatever device- 
specific actions are required to abort the request, preserving the contents of 
RO and R1. When the driver issues the RSB instruction, control is returned to 
EXE$READLOCKR. EXE$READLOCKR proceeds to abort or resubmit the I/O 
request. 


Otherwise, these routines return success status to their callers. 


* For read requests, MMG$IOLOCK performs an optimization for any nonvalid page contained within the buffer. 
It creates a demand-zero page rather than fault into memory the requested page. However, if the buffer 
extends to more than one page, this optimization is not possible. 
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A driver FDT routine that calls EXES}READLOCKR must distinguish between 
successful and unsuccessful status when it resumes, as shown in the following 
example: 


JSB G* EXE$READLOCKR 
BLBS BUF_LOCK_OK 
BUF_LOCK_FAIL: 
; clean up this $QI0 bookkeeping 


RSB 
BUF _LOCK_OK: 


;continue processing this I/O request 
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EXESSENSEMODE 


Copies device-dependent characteristics from the device’s UCB into R1, 
writes a success code into RO, and completes the I/O operation. 








module SYSQIOFDT 
input 

Location Contents 

R3 Address of IRP 

R4 Address of current PCB 

R5 Address of UCB 

R6 Address of CCB 

R7 Bit number of the !/O function code 

R8 Address of FDT entry for this routine 

OO(AP) Address of first function-dependent parameter of 

the $QlO request 

UCB$Q_DEVDEPEND Device-dependent status 
output 

Location Contents 

RO SS$_NORMAL 

R1 Device-dependent status 
synchronization | EXE$SENSEMODE is called as a driver FDT routine at IPL$_ASTDEL. 
DESCRIPTION _ A driver uses EXE$SENSEMODE as an FDT routine to process the sense- 
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device-mode (IO$_SENSEMODE) and sense-device-characteristics (IO$_ 
SENSECHAR) I/O functions. 


EXE$SENSEMODE loads the contents of UCB$Q_DEVDEPEND into R1, 
places SS$_NORMAL status into RO, and transfers control to EXE$FINISHIO 
to insert the IRP in the I/O postprocessing queue. 


Operating System Routines 


EXESSETCHAR, EXESSETMODE 


EXESSETCHAR, EXESSETMODE 


Write device-specific status and control information into the device's 
UCB and complete the I/O request (EXE$SETCHAR); or write the 
information into the IRP and deliver the IRP to the driver's start-I/O routine 





(EXESSETMODE). 
module SYSQIOFDT 
input 
Location Contents 
R3 Address of IRP 
R4 Address of current PCB 
R5 Address of UCB 
R6 Address of CCB 
R7 Bit number of the I/O function code 
R8 Address of FDT entry for this routine 
OO(AP) Address of location containing device 
characteristics quadword (p1) 
UCB$B_DEVCLASS Device class 
output 
Location Contents 
RO SS$_NORMAL, SS$_ACCVIO, or SS$_ 
ILLIOFUNC 
UCB$B_DEVCLASS Byte O of quadword (EXESSETCHAR, 
lIO$_SETCHAR function only) 
UCB$B_DEVTYPE Byte 1 of quadword (EXE$SETCHAR, 
lIOS_SETCHAR function only) 
UCB$W__DEVBUFSIZ Bytes 2 and 3 of quadword (EXE$SETCHAR) 
UCB$OQ_DEVDEPEND Bytes 4 through 7 of quadword (EXE$SETCHAR) 
IRP$L_MEDIA First longword of device characteristics 
(EXESSETMODE) 
IRP$L_MEDIA+4 Second longword of device characteristics 
(EXESSETMODE) 
synchronization EXE$SETCHAR or EXE$SETMODE is called as a driver FDT routine at IPL$_ 
ASTDEL. 
DESCRIPTION A driver uses EXE$SETCHAR or EXE$SETMODE as an FDT routine to 


process the set-device-mode (IO$_SETMODE) and set-device-characteristics 
(IL1O$_SETCHAR) functions. If setting device characteristics requires device 
activity or synchronization with fork processing, the driver’s FDT entry must 
specify EXE$SETMODE. Otherwise, it can specify EXE$SETCHAR. 
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EXE$SETCHAR and EXE$SETMODE examine the current value of UCB$B_ 
DEVCLASS to determine whether the device permits the specified function. 
If the device class is disk (DC$_DISK), the routines place SS$_ILLIOFUNC 
status in RO and transfer control to EXE$ABORTIO to terminate the request. 


EXE$SETCHAR and EXE$SETMODE then ensure that the process has read 
access to the quadword containing the new device characteristics. If it does 
not, the routines place SS$_ACCVIO status in RO and transfer control to 
EXE$ABORTIO to terminate the request. 


If the request passes these checks, EXESSETCHAR and EXE$SETMODE 
proceed as follows: 


EXE$SETCHAR stores the specified characteristics in the UCB. For an 
IO$_SETCHAR function, the device type and class fields (UCB$B_ 
DEVCLASS and UCB$B_DEVTYPE, respectively) receive the first word 
of data. For both IO$_SETCHAR and IO$_SETMODE functions, 
EXE$SETCHAR writes the second word into the default-buffer-size 
field (UCBSW_DEVBUFSIZ) and the third and fourth words into the 
device-dependent-characteristics field (UCB$Q_DEVDEPEND). 


Finally, EXE$SETCHAR stores normal completion status (SS$_NORMAL) 
in RO and transfers control to EXE$FINISHIO to insert the IRP in the I/O 
postprocessing queue. 


EXE$SETMODE stores the specified quadword of characteristics in 
IRP$L_MEDIA, places normal completion status (SS$_.NORMAL) in 
RO, and transfers control to EXE$QIODRVPKT to deliver the IRP to the 
driver’s start-I/O routine. 


The driver’s start-I/O routine copies data from IRP$L_MEDIA and the 
following longword into UCB$W_DEVBUFSIZ, UCB$Q_DEVDEPEND, and, 
if the I/O function is IO$_SETCHAR, UCB$B_DEVCLASS and UCB$B_ 
DEVTYPE as well. 


EXE$SNDEVMSG 


Builds and sends a device-specific message to the mailbox of a system 
process, such as the job controller or OPCOM. 


Operating System Routines 


EXESSNDEVMSG 





module MBDRIVER 
input 
Location Contents 
R3 Address of mailbox UCB 
R4 Message type 
R5 Address of device UCB 
UCBSW_UNIT Device unit number 
UCB$L_DDB Address of device DDB 
DDB$T_NAME and Device controller name 
mailbox UCB fields 
output 
Location Contents 
RO SS$_NORMAL, SS$_MBTOOSML, SS$_MBFULL, 
SS$_INSFMEM| or SS$_NOPRIV 
R1 through R4 Destroyed 
synchronization Because EXE$SNDEVMSG raises IPL to IPL$_MAILBOX and obtains the 
MAILBOX spin lock in a VMS multiprocessing environment, its caller cannot 
be executing above IPL$_MAILBOX. EXE$SNDEVMSG returns contro! to its 
caller at the caller’s IPL. The caller retains any spin locks it held at the time 
of the call. 
DESCRIPTION — EXE$SNDEVMSG builds a 32-byte message on the stack that includes the 


following information: 


Bytes Contents 
O and 1 Low word of R4 (message type) 
2 and 3 Device unit number (UCB$W_UNIT) 


4 through 31 Counted string of device controller name, formatted as 


node$controller for clusterwide devices 


EXE$SNDEVMSG then calls EXESWRTMAILBOX to send the message to a 
mailbox. 
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EXE$SNDEVMSG can fail for any of the following reasons: 


The message is too large for the mailbox (SS$_MBTOOSML). 
The message mailbox is full of messages (SS$_MBFULL). 


The system is unable to allocate memory for the message (SS$_ 
INSFMEM). 


The caller lacks privilege to write to the mailbox (SS$_NOPRIV). 


EXESWRITE 


Operating System Routines 
EXESWRITE 


Translates a logical write function into a physical write function, transfers 
$QlO system service parameters to the IRP, validates and prepares a 
user buffer, and proceeds with or aborts a direct-|/O, DMA read/write 
operation. 





module SYSQIOFDT 
input 
Location Contents 
R3 Address of IRP. 
R4 Address of current PCB. 
R5 Address of UCB. 
R6 Address of CCB. 
R7 Bit number of the 1/O function code. 
R8 Address of FDT entry for this routine. 
OO(AP) Virtual address of buffer (p1). 
O4(AP) Number of bytes in transfer (p2). The maximum 
number of bytes that EXESWRITE can transfer is 
65,535 (128 pages minus one byte). 
12(AP) Carriage control byte (p4). 
IRP$W_FUNC 1/0 function code. 
output 
; Location Contents 
RO, R1, R2 Destroyed 
IRP$L_IOST2 p4 
IRP$W_.FUNC Logical read function code converted to physical 
IRP$\W_STS IRP$V_FUNC clear, indicating a write function 
IRP$L_SVAPTE System virtual address of the process page-table 
entry (PTE) that maps the first page of the buffer 
IRP$W_BOFF Byte offset to start of transfer in page 
IRP$L_BCNT Size of transfer in bytes 
synchronization = EXE$WRITE is called as a driver FDT routine at IPL$_ASTDEL. 
DESCRIPTION A driver uses EXE$WRITE as an FDT routine when the driver must read 


from the user-specified buffer. Because EXE$WRITE transfers control to 
EXE$QIODRVPKT if its operations are successful or EXES$ABORTIO if they 
are not, it must be the last FDT routine called to perform the preprocessing 
of write I/O requests. A driver cannot use EXE$WRITE for buffered I/O 
operations. 
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EXE$WRITE performs the following functions: 


e Writes the p4 argument of the $QIO request into IRP$L_IOST2 (IRP$B_ 
CARCON). 


e Translates a logical write function to a physical write function. 


e Examines the size of the transfer, as specified in the p2 argument of the 
$QIO request, and takes one of the following actions: 


— If the transfer byte count is zero, EXESWRITE transfers control to 
EXE$QIODRVPKT to deliver the IRP to the driver’s start-I/O routine. 
The driver start-I/O routine should check for zero-length buffers to 
avoid mapping them to UNIBUS, Q22 bus, MASSBUS, or VAXBI 
node space. An attempted mapping can cause a system failure. 


— Ifthe byte count is not zero, EXE$READ loads the byte count and the 
starting address of the transfer into R1 and RO, respectively, and calls 
EXE$WRITELOCK. 


EXE$WRITELOCK calls EXE$WRITELOCKR. 


EXE$WRITELOCKR calls EXES;WRITECHKR, which performs the following 
tasks: 


¢ Moves the transfer byte count into IRP$L_BCNT. If the byte count is 
negative, it returns SS$_BADPARAM status to EXES}WRITELOCKR. 


¢ Determines whether the specified buffer is read accessible for a write I/O 
function, with one of the following results: 


— If the buffer allows read access, EXES$/WRITECHKR returns SS$_ 
NORMAL to EXE$WRITELOCKR. 


— If the buffer does not allow read access, EXE$WRITECHKR returns 
SS$_ACCVIO status to EXE$WRITELOCKR. 


If EXES$WRITECHKR succeeds, EXE$WRITELOCKR moves into IRP$W_ 
BOFF the byte offset to the start of the buffer and calls MMG$IOLOCK. 
MMG$IOLOCK attempts to lock into memory those pages that contain the 
buffer, with one of the following results: 


e If MMG$IOLOCK succeeds, EXE$WRITELOCKR stores in IRP$L— 
SVAPTE the system virtual address of the process PTE that maps the 
first page of the buffer, and returns control to EXES$WRITE. EXE$WRITE 
transfers control to EXE$QIODRVPKT to deliver the IRP to the driver’s 
start-I/O routine. 


°¢ If MMG$IOLOCK fails, it returns SS$_ACCVIO, SS$_INSFWSL, or page 
fault status to EXE$>WRITELOCKR. 


If either EXE$WRITECHKR or MMG$IOLOCK returns an error status, 
EXE$WRITELOCKR transfers control to EXE$ABORTIO. 


Operating System Routines 
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EXES$WRITECHK, EXESWRITECHKR 


module 


input 


output 


synchronization 


Verify that a process has read access to the pages in the buffer specified 
in a $QlO request. 


SYSQIOFDT 

Location Contents 

RO Virtual address of buffer 

R1 Size of transfer in bytes 

R3 Address of IRP 

Location Contents 

RO Virtual address of buffer (EXE$WRITECHK), SS$_ 
NORMAL (EXESWRITECHKR), or error status 

R1 Size of transfer in bytes 

R2 O, indicating a write function 

IRP$W_STS IRP$V_FUNC clear, indicating a write function 

IRP$L_BCNT Size of transfer in bytes 


EXE$WRITECHK and EXE$WRITECHKR are called by a driver FDT routine 
at IPL$_ASTDEL. 





DESCRIPTION 


A driver uses either of these routines to check the read accessibility of a 
user-specified buffer. A driver typically calls EXESWRITECHKR instead of 
EXE$WRITECHK when it must regain control before the request is aborted in 
the event the buffer is inaccessible. 


EXE$WRITECHK calls EXES}WRITECHKR. 
EXE$WRITECHKR performs the following tasks: 


¢ Moves the transfer byte count into IRP$L_BCNT. If the byte count is 
negative, it returns SS$_BADPARAM status to its caller. 


e¢ Determines if the specified buffer is read accessible for a write I/O 
function, with one of the following results: 


— If the buffer allows read access, EXE/WRITECHKR returns SS$_ 
NORMAL to its caller. 


— If the buffer does not allow read access, EXE$WRITECHKR returns 
SS$_ACCVIO status to its caller. 
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If the initial call was to EXE$WRITECHK, and EXE$WRITECHKR returns 
error status, EXE$WRITECHK transfers control to EXE$ABORTIO to terminate 
the I/O request. If the initial call was to EXESWRITECHKR, and an error 
occurs, EXE$WRITECHKR returns control to the driver. Otherwise, these 
routines return success status to their callers. 


A driver FDT routine that calls EXE$SWRITECHKR must distinguish between 
successful and unsuccessful status when it resumes, as shown in the following 
example: 


JSB G*EXE$WRITECHKR 
BLBS  BUF_ACCESS_OK 
BUF _ACCESS_FAIL: 
; clean up this $QIO bookkeeping 


JSB G°EXE$ABORTIO 
BUF_ACCESS_OK: 


;continue processing this I/O request 


Operating System Routines 
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EXESWRITELOCK, EXESWRITELOCKR 


Validate and prepare a user buffer for a direct-|/O, DMA write operation. 


module SYSQIOFDT 
input 
Location Contents 
RO Virtual address of buffer 
R1 Number of bytes in transfer 
R3 Address of IRP 
R4 Address of current PCB 
R5 Address of UCB 
R6 Address of CCB 
R7 Bit number of the |/O function code 
output 
Location Contents 
RO SS$_NORMAL 
R1 System virtual address of the process page-table 
entry (PTE) that maps the first page of the buffer 
R2 O, indicating a write function 
IRPSW_STS IRP$V_FUNC clear, indicating a write function 
IRP$L_SVAPTE System virtual address of the PTE that maps the 
first page of the buffer 
IRP$W_BOFF Byte offset to start of transfer in page 
IRP$L_BCNT Size of transfer in bytes 


synchronization | EXE$WRITELOCK and EXE$WRITELOCKR are called by a driver FDT routine 
at IPL$_ASTDEL. 





DESCRIPTION A driver typically calls EXE$SWRITELOCKR instead of EXE$WRITELOCK 
when it must lock multiple areas into memory for a single I/O request and 
must regain control, if the request is to be aborted, to unlock these areas. 

A driver uses either of these routines when it must read from the user- 
specified buffer and it is not desirable to automatically deliver the IRP to the 
device unit after the buffer has been successfully locked. A driver cannot use 
EXE$WRITELOCK or EXE$WRITELOCKR for buffered I/O operations. 


EXE$WRITELOCK calls EXESWRITELOCKR. 


EXE$WRITELOCKR calls EXE$WRITECHKR, which performs the following 
tasks: 


¢ Moves the transfer byte count into IRP$L_BCNT. If the byte count is 
negative, it returns SS$_BADPARAM status to EXESWRITELOCKR. 
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e Determines if the specified buffer is write accessible for a write I/O 
function, with one of the following results: 


— If the buffer allows read access, EXE$SWRITECHKR returns SS$_ 
NORMAL to EXE$WRITELOCKR. 


— If the buffer does not allow read access, EXE$}WRITECHKR returns 
SS$_ACCVIO status to EXE$SWRITELOCKR. 


If EXESWRITECHKR succeeds, EXE$WRITELOCKR moves into IRP$W_ 
BOFF the byte offset to the start of the buffer and calls MMG$IOLOCK. 
MMGSIOLOCK attempts to lock into memory those pages that contain the 
buffer, with one of the following results: 


e If MMG$IOLOCK succeeds, EXESWRITELOCKR stores in IRP$L— 
SVAPTE the system virtual address of the process PTE that maps the 
first page of the buffer, and returns success status to its caller. 


e If MMG$IOLOCK fails, it returns SS$_ACCVIO, SS$_INSFWSL, or page 
fault status to EXE$}WRITELOCKR. 


If the initial call was to EXESWRITELOCK and either EXE$WRITECHKR or 
MMGSIOLOCK returns an error status other than a page fault condition, 
EXE$WRITELOCKR transfers control to EXESABORTIO. In the event of a 
page fault, EXESWRITELOCKR adjusts direct I/O count and AST count to 
the values they held before the I/O request, deallocates the IRP, and restarts 
the I/O request at the $QIO system service. This procedure is carried out 
so that the user process can receive ASTs while it waits for the page fault to 
complete. Once the page is faulted into memory, the $QIO system service 
will resubmit the I/O request. 


If the initial call was to EXE$WRITELOCKR and an error occurs, 
EXE$WRITELOCKR, by means of a coroutine call, returns control to the 
driver’s FDT routine with status in RO. The driver performs whatever device- 
specific actions are required to abort the request, preserving the contents of 
RO and R1. When the driver issues the RSB instruction, control is returned to 
EXE$WRITELOCKR. EXESWRITELOCKR proceeds to abort the I/O request. 


Otherwise, these routines return success status to their callers. 


A driver FDT routine that calls EXESWRITELOCKR must distinguish between 
successful and unsuccessful status when it resumes, as shown in the following 
example: 


JSB G*EXE$WRITELOCKR 
BLBS BUF_LOCK_OK 
BUF_LOCK_FAIL: 
; clean up this $QI0 bookkeeping 


RSB 
BUF __LOCK_OK: 


;continue processing this I/O request 
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EXESWRTMAILBOX 

Sends a message to a mailbox. 

module MBDRIVER 

input 
Location Contents 
R3 Message size 
R4 Message address 
R5 Address of mailbox UCB 
Mailbox UCB fields 

output 
Location Contents 
RO SS$_NORMAL, SS$_MBTOOSML, SS$_MBFULL, 

SS$_INSFMEM, or SS$_NOPRIV 

R1 and R2 Destroyed 

synchronization Because EXE${WRTMAILBOX raises IPL to IPL$_MAILBOX and obtains the 
MAILBOX spin lock in a VMS multiprocessing environment, its caller cannot 
be executing above IPL$_MAILBOX. EXESWRTMAILBOxX returns control to 
its caller at the caller’s IPL. The caller retains any spin locks it held at the 
time of the call. 

DESCRIPTION EXE$WRTMAILBOX checks fields in the mailbox UCB (UCB$W_BUFQUO, 


UCB$W_DEVBUFSIZ) to determine whether it can deliver a message of the 
specified size to the mailbox. It also checks fields in the associated ORB to 
determine whether the caller is sufficiently privileged to write to the mailbox. 
Finally, it calls EXESALONONPAGED to allocate a block of nonpaged pool to 
contain the message. If it fails any of these operations, EXES;WRTMAILBOX 
returns error status to its caller. 


If it is successful thus far, EXES};WRTMAILBOX creates a message and delivers 
it to the mailbox’s message queue, adjusts its UCB fields accordingly, and 
returns success status to its caller. 
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EXE$ZEROPARM 


EXE$ZEROPARM 


Processes an I/O function code that requires no parameters. 


module SYSQIOFDT 
input 
R3 Address of IRP 
R4 Address of current PCB 
R5 Address of UCB 
R6 Address of CCB 
R7 Bit number of the I/O function code 
R8 Address of FDT entry for this routine 
output 
Location Contents 
IRP$L_MEDIA 0 


synchronization | EXE$ZEROPARM is called as a driver FDT routine at IPL$_ASTDEL. 





DESCRIPTION — EXE$ZEROPARM processes an I/O function code that describes an I/O 
operation completely without any additional function-specific arguments. It 
clears IRP$L_MEDIA and transfers control to EXESQIODRVPKT to deliver 
the IRP to the driver. 
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IOCSALOALTMAP, IOC$ALOALTMAPN, IOCSALOALTMAPSP 


IOCSALOALTMAP, IOCSALOALTMAPN, 


lIOCSALOALTMAPSP 


Allocate a set of Q22-bus alternate map registers. 


module 


input 


Location 
R3 


R4 


R5 
UCBSW._BCNT 
UCB$W_BOFF 
UCB$L_CRB 


CRB$L_INTD+ 
VEC$L_ADP 


CRB$L_INTD+ 
VEC$W_MAPALT 


ADP$W_MR2NREGAR, 
ADP$W_MR2FREGAR, 
ADP$L_MR2ACTMDR 


output 


Location 
RO 


R1 
R2 


CRB$L_INTD+ 
VEC$W_NUMALT 


CRB$L_INTD+ 
VEC$W_MAPALT 


ADP$W_MR2NREGAR, 
ADP$W_MR2FREGAR, 
ADP$L_MR2ACTMDR 


[SYSLOAJMAPSUBxxx 


Contents 


Number of alternate map registers to allocate 
(IOCSALOALTMAPN and IOC6ALOALTMAPSP 
only). The value should account for one extra 
register needed to prevent a transfer overrun. 


Number of first alternate map register to allocate 
(IOCSALOALTMAPSP only). 


Address of UCB. 
Transfer byte count (OCSALOALTMAP only). 
Byte offset in page ((OCSALOALTMAP only). 
Address of CRB. 
Address of ADP. 


VEC$V_ALTLOCK set indicates that alternate 
map registers have been permanently allocated to 
this controller. 


Alternate map register descriptor arrays. 


Contents 


SS$_NORMAL, SS$_INSFMAPREG, or 
SS$_SSFAIL 


Destroyed 
Address of ADP 
Number of alternate map registers allocated 


Starting alternate map register number 


Updated 
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|OCSALOALTMAP, IOCSALOALTMAPN, IOCSALOALTMAPSP 


synchronization 


Callers of IOC6ALOALTMAP, IOC$6ALOALTMAPN, or 
IOC$ALOALTMAPSP may be executing at fork IPL or above and must 
hold the corresponding fork lock in a VMS multiprocessing environment. 
Each routine returns control to its caller at the caller’s IPL. The caller retains 
any spin locks it held at the time of the call. 





DESCRIPTION 
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IOC$ALOALTMAP, IOC$ALOALTMAPN, and IOC6ALOALTMAPSP 
allocate a contiguous set of Q22-bus alternate map registers (registers 496 

to 8191) and record the allocation in the ADP and CRB. These routines differ 
in the way in which they determine the number and location of the alternate 
map registers they allocate: 


¢ IOC$ALOALTMAP calculates the number of needed map registers 
using the values contained in UCB$W_BCNT and UCB$W_BOFF. It 
automatically allocates one extra map register. When it is later called by 
the driver, IOC6LOADALTMAP marks this register invalid to prevent a 
transfer overrun. 


e IOC$ALOALTMAPN uses the value in R3 as the number of required 
registers. 


¢ IOC$ALOALTMAPSP uses the value in R3 as the number of required 
registers and attempts to allocate these registers starting at the one 
indicated by R4. 


If an odd number of map registers is required, these routines round this value 
up to an even multiple. 


If alternate map registers have been permanently allocated to the controller, 
IOC$ALOALTMAP, IOC$ALOALTMAPN, or IOC6ALOALTMAPSP returns 
successfully to its caller without allocating the requested map registers. 
Otherwise, it searches the alternate map register descriptor arrays for the 
required number of map registers. If there are not enough contiguous map 
registers available, the routine returns SS$_INSFMAPREG status. 


If the VAX system does not support alternate map registers, the routine exits 
with SS$_SSFAIL status. 
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lIOCSALOUBAMAP, IOC$ALOUBAMAPN 


IOCSALOUBAMAP, IOC$ALOUBAMAPN 


Allocate a set of UNIBUS map registers or a set of the first 496 Q22-bus 


module 


input 


output 


synchronization 


map registers. 


IOSUBNPAG 


Location 
R3 


R5 
UCB$W_BCNT 
UCB$W_BOFF 
UCB$L_CRB 


CRB$L_INTD+ 
VEC$L_ADP 


CRB$L_INTD+ 
VEC$W_MAPREG 


ADP$W_MRNREGARY, 
ADP$W_MRFREGARY, 
ADP$L_MRACTMDRS 


Location 
RO 
R1 
R2 


CRB$L_INTD+VEC$B_ 
NUMREG 


CRB$L_INTD+VECSW_ 
MAPREG 


ADP$W_MRNREGARY, 
ADP$W_MRFREGARY, 
ADP$L_MRACTMDRS 


Contents 


Number of map registers to allocate 
(IOCS6ALOUBAMAPN only). The value should 
account for one extra register needed to prevent 
a transfer overrun. 


Address of UCB. 
Transfer byte count (IOC6ALOUBAMAP only). 
Byte offset in page (IOC6ALOUBAMAP only). 
Address of CRB. 
Address of ADP. 


VEC$V_MAPLOCK set indicates that map 
registers have been permanently allocated to 
this controller. 


Map register descriptor arrays. 


Contents 
SS$_NORMAL or O 
Destroyed 

Address of ADP 


Number of map registers allocated 
Starting map register number 


Updated 


The caller of IOCSALOUBAMAP or IOC6ALOUBAMAPN may be executing 
at fork IPL or above and must hold the corresponding fork lock in a VMS 
multiprocessing environment. Either routine returns control to its caller at the 
caller’s IPL. The caller retains any spin locks it held at the time of the call. 


C-63 


Operating System Routines 
lIOCSALOUBAMAP, IOC$ALOUBAMAPN 





DESCRIPTION 
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IOC$ALOUBAMAP and IOC6ALOUBAMAPN allocate a contiguous set of 
UNIBUS map registers or a set of the first 496 Q22-bus map registers and 
record the allocation in the ADP and CRB. These routines differ in the way in 
which they determine the number of the map registers they allocate: 


¢ IOC$ALOUBAMAP calculates the number of needed map registers 
using the values contained in UCBSW_BCNT and UCB$W_BOFF. It 
automatically allocates one extra map register. When it is later called by 
the driver, IOCSLOADUBAMAP marks this register invalid to prevent a 
transfer overrun. 


¢ JOC$ALOUBAMAPN uses the value in R3 as the number of required 
registers. . 


If an odd number of map registers is required, both routines round this value 
up to an even multiple. 


If map registers have been permanently allocated to the controller, 
IOC$ALOUBAMAP or IOC6ALOUBAMAPN returns successfully to its 

caller without allocating the requested map registers. Otherwise, it searches 
the map register descriptor arrays for the required number of map registers. If 
there are not enough contiguous map registers available, the routine returns 
an error status of zero to its caller. 
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lIOCSAPPLYECC 


IOCSAPPLYECC 


Applies an ECC correction to data transferred from a disk device into 
memory. 





module IOSUBRAMS 
input 
Location Contents 
RO Number of bytes of data that have been 
transferred, not including the block to be 
corrected; this must be a multiple of 512 bytes 
R5 Address of UCB 
UCB$W_BCNT Length of transfer in bytes 
UCB$W_EC1 Starting bit number of the error burst 
UCB$W_EC2 Exclusive OR correction pattern 
UCB$L_SVPN Address of system PTE for a page that is 
available for use by driver 
UCB$L_SVAPTE System virtual address of PTE that maps the 
transfer 
output 
Location Contents — 
RO, R1, R2 Destroyed 
UCB$W_DEVSTS UCB$V_ECC set to indicate that an ECC 
correction was made 
synchronization §IOC$APPLYECC executes at the caller’s IPL, obtains no spin locks, and 
returns control to its caller at its caller’s IPL. 
DESCRIPTION  [I0OC$APPLYECC corrects data transferred from a disk device to memory by 


performing an exclusive-OR operation on the data and applying a correction 
pattern from the UCB. IOC$APPLYECC also sets a UCB bit (UCB$V_ECC in 
UCB$W_DEVSTS) to indicate that it has made an ECC correction. 


Note that, to use this routine, the driver must define the local UCB disk 
extension, as described in Section A.14. 
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Operating System Routines 
IOC$CANCELIO 


IOC$CANCELIO 


Conditionally marks a UCB so that its current 1/O request will be canceled. 





module IOSUBNPAG 
input 
Location Contents 
R2 Channel index number 
R3 Address of IRP 
R4 Address of current PCB 
R5 Address of UCB 
IRP$L_PID Process identification of the process that queued 
the 1/O request 
IRP$W_CHAN 1/O request channel index number 
PCB$L_PID Process identification of the process that 
requested cancellation 
UCB$L_STS UCB$V_BSY set if device is busy, clear if device 
is idle 
output 
Location Contents 
UCB$L_STS UCB$V_CANCEL set if the 1/O request should be 
canceled 
synchronization JIOC$CANCELIO executes at its caller’s IPL, obtains no spin locks, and 
returns control to its caller at the caller’s IPL. It is usually called by 
EXE$CANCEL (if specified in the DDT as the driver’s cancel-I/O routine) 
at fork IPL, holding the corresponding fork lock in a VMS multiprocessing 
environment. 
DESCRIPTION  IOC$CANCELIO cancels I/O to a device in the following device-independent 


C—66 


manner: 


1 It confirms that the device is busy by examining the device-busy bit in 
the UCB status longword (UCB$V_BSY in UCB$L_STS). 


2 It confirms that the IRP in progress on the device originates from the 
current process (that is, the contents of IRP$L_PID and PCB$L_PID are 


identical). 


3 It confirms that the specified channel-index number is the same as the 
value stored in the IRP’s channel-index field (IRP$W_CHAN). 


4 It sets the cancel-I/O bit in the UCB status longword (UCB$V_CANCEL 


in UCB$L_STS). 


IOCS$DIAGBUFILL 


Fills a diagnostic buffer if the original $O10 request specified such a buffer. 
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IOCSDIAGBUFILL 





module IOSUBNPAG 
input 
Location Contents 
R4 Address of device’s CSR 
R5 Address of UCB 
UCB$L_IRP Address of current IRP 
IRP$W_STS IRP$V_DIAGBUF set if a diagnostic buffer exists 
IRP$L __DIAGBUF Address of diagnostic buffer, if one is present 
UCB$B_ERTCNT Final error retry count 
UCB$L_DDB Address of DDB 
DDB$L_DDT Address of DDT 
DDT$L_REGDUMP Address of driver's register dumping routine 
EXE$GO_SYSTIME Current system time (time at 1/O request 
completion) 
output 
Location Contents 
RO, R1 Destroyed 
R2 Address of DDT 
R3 Address of IRP 
R4 Address of device’s CSR 
R5 Address of UCB 
synchronization The caller of IOC$DIAGBUFILL may be executing at or above fork IPL 
and must hold the corresponding fork lock in a VMS multiprocessing 
environment. IOC$DIAGBUFILL returns control to its caller at the caller’s 
IPL. The caller retains any spin locks it held at the time of the call. 
DESCRIPTION A device driver fork process calls IOC$DIAGBUFILL at the end of I/O 


processing but before releasing the I/O channel. IOC$DIAGBUFILL stores 
the I/O completion time and the final error retry count in the diagnostic 
buffer. (IOC$INITIATE has already placed the I/O initiation time in the first 
quadword of the buffer.) IOCS$DIAGBUFILL then calls the driver’s register 
dumping routine, which fills the remainder of the buffer, and returns to its 


caller. 
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IOCSINITIATE 


IOCSINITIATE 


module 


input 


output 


synchronization 
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Initiates the processing of the next I/O request for a device unit. 


IOSUBNPAG 


Location 

R3 

R5 
CPU$L__PHY_CPUID 
IRP$L_SVAPTE 


IRP$W_BOFF 
IRP$L_BCNT 
IRPS$W_STS 
IRP$L_DIAGBUF 
EXE$GQ_SYSTIME 
UCBS$L_DDB 
UCB$L_DDT 
UCBSL_AFFINITY 


DDT$L_START 


Location 

RO, R1 

UCB$L _IRP 
UCB$L_SVAPTE 
UCB$W_BOFF 
UCB$W_BCNT 
UCB$L_STS 
Diagnostic buffer 


Contents 

Address of IRP 

Address of UCB 

CPU ID of local processor 


Address of system buffer (buffered I/O) or 
system virtual address of the PTE that maps 
process buffer (direct 1/O) 


Byte offset of start of buffer 

Size in bytes of transfer 

IRP$V_DIAGBUF set if a diagnostic buffer exists 
Address of diagnostic buffer, if one is present 
Current system time (when I/O processing began) 
Address of DDB 

Address of DDT 

Device’s affinity mask 

Address of driver start-I/O routine 


Contents 

Destroyed 

Address of IRP 

IRP$L_SVAPTE 

IRP$W_BOFF 

IRP$L_BCNT (low-order word) 
UCB$V_CANCEL and UCB$V_TIMOUT cleared 
Current system time (first quadword) 


IOC$INITIATE is called at fork IPL with the corresponding fork lock held in 
a VMS multiprocessing system. Within this context, it transfers control to the 


driver’s start-I/O routine. 


Operating System Routines 
IOCSINITIATE 





DESCRIPTION 


IOCSINITIATE creates the context in which a driver fork process services an 
I/O request. IOC$INITIATE creates this context and activates the driver’s 
start-I/O routine in the following steps: 


Checks the CPU ID of the local processor against the device’s affinity 
mask to determine whether the local processor can initiate the I/O 
operation on the device. If it cannot, IOC$SINITIATE takes steps to initiate 
the I/O function on another processor in a VMS multiprocessing system. 
It then returns to its caller. 


Stores the address of the current IRP in UCB$L_IRP. 
Copies the transfer parameters contained in the IRP into the UCB: 


— Copies the address of the system buffer (buffered I/O) or the system 
virtual address of the PTE that maps process buffer (direct I/O) from 
IRP$L_SVAPTE to UCB$L_SVAPTE 


— Copies the byte offset within the page from IRP$W_BOFF to 
UCB$W_BOFF 


— Copies the low-order word of the byte count from IRP$L_—BCNT to 
UCB$W_BCNT 


Clears the cancel-I/O and timeout bits in the UCB status longword 
(UCB$V_CANCEL and UCB$V_TIMOUT in UCB$L_STS). 


If the I/O request specifies a diagnostic buffer, as indicated by IRP$V_ 
DIAGBUF in IRP$W_STS, stores the system time in the first quadword 
of the buffer to which IRP$L_DIAGBUF points (the $QIO system service 
having already allocated the buffer). 


Transfers control to the driver’s start-I/O routine. 
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lOCSIOPOST 


lIOCSIOPOST 


Performs device-independent I/O postprocessing and delivers the results 
of an |/O request to a process. 


module 


input 
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IOCIOPOST 


Location 
CPU$L_PSFL 


IRP$L_PID 


IRP$L_UCB 
IRP$W_STS 


IRP$L_DIAGBUF 
IRP$L_SVAPTE 


IRP$W_BOFF 
IRP$L_BCNT 
IRP$L__OBCNT 
IRP$L_IOST 1 
IRPSW_CHAN 
IRP$L_IOSB 
IRP$B_RMOD 


IRP$B_EFN 
UCB$W_OLEN 
UCB$L_DEVCHAR 
PCB$W_DIOCNT 
PCBSW_BIOCNT 
JIBSL_BYTCNT 
CCB$W_IOC 
CCB$L_—DIRP 


Contents 


Head of the CPU-specific |/O postprocessing 
queue 


Process identification of the process that initiated 
the |/O request 


Address of UCB 


IRP$V_BUFIO set if buffered-I/O request, clear if 
direct-I/O request; IRP$V_PHYSIO set if physical- 
1/O function; IRP$V_EXTEND set if an IRPE is 
linked to this IRP; IRP$V_KEY set if IRP$L_ 
KEYDESC contains the address of an encryption 
key buffer; IRP$V_FUNC set if read function, 
clear if write function; IRP$V_DIAGBUF set if 
diagnostic buffer exists; IRP$V_MBXIO set if 
mailbox read function 


Address of diagnostic buffer, if one is present 


Address of system buffer (buffered !/O) or 
system virtual address of the PTE that maps 
process buffer (direct |/O) 


Byte offset of start of buffer 

Size in bytes of transfer 

Original byte count for virtual I/O transfer 
First 1/O status longword 

1/O request channel index number 
Address of 1/0 status block, if specified 


Access mode of I/O request; ACB$V_QUOTA 
set if request specified AST 


Event flag number 

Length of pending-!/O queue 

DEV$V_FOD set if file-oriented device 
Process’s direct-I/O count 

Process’s buffered-!/O count 

Job byte count quota 

Number of outstanding |/O requests on channel 
Address of IRP for requested deaccess 
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IOCSIOPOST 
output 
Location Contents 
CPU$L_PSFL Updated 
UCBSW_OLEN Decremented 
PCB$W_DIOCNT Incremented for a direct-|/O request 
PCB$W_BIOCNT Incremented for a buffered I/O request 
JIB$L_BYTCNT Updated for buffered 1/O request 
CCB$W_IOC Decremented 
CCB$L_DIRP Cleared if channel is idle 
synchronization [OC$IOPOST executes in response to an interrupt granted at IPL$_IOPOST. 
It performs some of its functions in a special kernel-mode AST that executes 
within process context at IPL$_ASTDEL. It obtains and releases the various 
spin locks required to deallocate nonpaged pool and adjust process quotas. 
DESCRIPTION This interrupt service routine processes IRPs in an I/O postprocessing 


queue, gaining control when the processor grants a software interrupt. at 
IPL$_IOPOST. When a processor’s I/O postprocessing queue is empty, 
IOC$IOPOST dismisses the interrupt with an REI instruction. 


IOCSIOPOST performs several tasks to complete either a direct- or buffered- 
I/O request: 


¢ For a buffered-I/O read request, it copies data from the system buffer 
to the process buffer. If it cannot write to the process buffer, it returns 
SS$_ACCVIO status. For read and write requests, it releases the system 
buffer to nonpaged pool. 


e For a direct-I/O request, it unlocks those process buffer pages that were 
locked for the I/O transfer. (If an IRPE exists, the unlocked pages include 
any defined in the IRPE area descriptors.) 


IOC$IOPOST performs the following tasks for both direct and buffered I/O 
requests: 


e¢ Decrements the device’s pending-I/O queue length 
e Adjusts direct-I/O or buffered-I/O quota use 
e Sets an event flag if one was specified in the $QIO system service call 


¢ Copies I/O completion status from the IRP to the process’s I/O status 
block (if one was specified in the $QIO system service call). 


¢ Queues a user mode AST (if specified) to the process 


e Copies the diagnostic buffer (if specified) from system to process space 
and releases the system buffer 


¢ Deallocates the IRP and any IRPEs 


Note that many of these operations are performed within process context by 
the special kernel-mode AST IOC$IOPOST queues to the process. 
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lIOCSLOADALTMAP 


IOCSLOADALTMAP 


Loads a set of Q22-bus alternate map registers. 





module [SYSLOAJMAPSUBxxx 
macro LOADALT 
input 
Location Contents 
R5 Address of UCB 
UCB$W_BCNT Number of bytes in transfer 
UCB$W_BOFF Byte offset in first page of transfer 
UCB$L_SVAPTE System virtual address of PTE for first page of 
transfer 
UCB$L_CRB Address of CRB 
CRB$L_INTD+ Number of alternate map registers allocated 
VEC$W_NUMALT 
CRBS$L_INTD+ Number of first alternate map registér allocated 
VECS$W_MAPALT 
CRB$L_INTD+ Address of ADP 
VEC$L_ADP 
ADP$L_MR2ADDR Address of the first Q22-bus alternate map 
register 
output 
Location Contents 
RO SS$_NORMAL, SS$_INSFMAPREG, or 
SS$_SSFAIL 
R1, R2 Destroyed 
synchronization A driver fork process calls IOC$LOADALTMAP at fork IPL, holding 
the corresponding fork lock in a VMS multiprocessing environment. 
IOC$LOADALTMAP returns control to its caller at the caller’s IPL. The 
caller retains any spin locks it held at the time of the call. 
DESCRIPTION A driver fork process calls IOC$LOADALTMAP to load a previously-allocated 
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set of alternate map registers with page-frame numbers (PFNs). This enables 
a device DMA transfer to or from the buffer indicated by the contents of 
UCB$L_SVAPTE, UCB$SW_BCNT, and UCB$W_BOFF. 


Operating System Routines 
l|OC$LOADALTMAP 


IOC$LOADALTMAP confirms that sufficient alternate map registers have 
been previously allocated. If not, it issues a UBMAPEXCED bugcheck. 
Otherwise, it loads the appropriate PFN into each map register and sets the 
map register valid bit. It clears the last map register. This last invalid register 
prevents a transfer overrun. 


If the VAX system does not support alternate map registers, the routine exits 
with SS$_SSFAIL status. 
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lIOCS$LOADMBAMAP 


lIOCS$LOADMBAMAP 


module 


macro 


input 


output 


synchronization 


Loads MASSBUS map registers. 


LOADMREG 

LOADMBA 

Location Contents 

R4 Address of MBA configuration register 
(MBA$L_CSR) 

R5 Address of UCB 

UCB$W_BCNT Number of bytes in transfer 

UCB$W_BOFF Byte offset in first page of transfer 


UCB$L_SVAPTE 


System virtual address of PTE for first page of 
transfer 


MBA$L_MAP Address of first MASSBUS map register 
Location Contents 
RO, R1, R2 Destroyed 


A driver fork process calls IOC$LOADMBAMAP at fork IPL. 
IOC$LOADMBAMATP returns control to its caller at the caller’s IPL. 





DESCRIPTION 
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Driver fork processes for DMA transfers call IOCSLOADMBAMAFP to load 
MASSBUS adapter map registers with page-frame numbers (PFNs). 


IOC$LOADMBAMAP uses the contents of UCB$L_SVAPTE, UCB$W_ 
BCNT, and UCB$W_BOFF to determine the number of pages involved in the 
transfer. It then copies the page frame numbers from the page-table entries 
associated with this buffer into map registers, starting with map register 0. 


IOC$LOADMBAMATP also loads the negated transfer size into the MASSBUS 
adapter’s byte count register (MBA$L_—BCR) and the byte offset of the transfer 
into the MASSBUS adapter’s virtual address register (MBA$L_VAR). It clears 
the last map register. This last invalid register prevents a transfer overrun. 


The driver must own the MASSBUS adapter, and thus its map registers, 
before it calls this routine. 


Operating System Routines 


IOCSLOADUBAMAP, IOCSLOADUBAMAPA 


IOCSLOADUBAMAP, IOC$LOADUBAMAPA 


Load a set of UNIBUS map registers or a set of the first 496 Q22 bus map 





registers. 
module LOADMREG 
macro LOADUBA 
input 
Location Contents 
R5 Address of UCB 
UCBSW_BCNT Number of bytes in transfer 
UCB$W_BOFF Byte offset in first page of transfer 
UCB$L_SVAPTE System virtual address of PTE for first page of 
. transfer 
UCB$L_CRB Address of CRB 
CRB$L_INTD+ Number of map registers allocated 
. VEC$B_NUMREG 
CRB$L_INTD+ Number of first map register allocated 
VEC$W_MAPREG 
CRB$L_INTD+ Data path specifier; VEC$V_LWAE set if 
VEC$B_DATAPATH longword buffering is used, clear if quadword 
buffering is used 
CRB$L_INTD+ Address of ADP © 
VEC$L_ADP 
UBAS$L_MAP Address of first UNIBUS or 022 bus map register 
UCB$L_SVAPTE System virtual address of PTE for the first page 
of the transfer 
output 
Location Contents 
RO, R1, R2 Destroyed 
synchronization A driver fork process calls IOC$LOADUBAMAP or IOC$LOADUBAMAPA 
at fork IPL, holding the corresponding fork lock in a VMS multiprocessing 
environment. Either routine returns control to its caller at the caller’s IPL. 
The caller retains any spin locks it held at the time of the call. 
DESCRIPTION _ A driver fork process calls IOC$LOADUBAMAP or IOC$6LOADUBAMAPA 


to load a previously-allocated set of map registers with page-frame numbers 
(PFNs). This enables a device DMA transfer to or from the buffer indicated 
by the contents of UCB$L_SVAPTE, UCBSW_BCNT, and UCB$W_BOFF. 
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Either IOC6LOADUBAMAP or IOCSLOADUBAMAPA confirms that 
sufficient map registers have been previously allocated. If not, it issues a 
UBMAPEXCED bugcheck. Otherwise, it loads into each map register the 
appropriate PFN and data-path number. It sets the map register valid bit and, 
if VEC$V_LWAE is set in VEC$B_DATAPATH, the longword-access-enable 
bit. 


IOC$LOADUBAMAP checks the low bit of UCB$W_BOFF to determine 
whether the transfer is byte-aligned or word-aligned. If the low bit is set, it 
sets the byte-offset bit in each map register. Drivers for byte-aligned UNIBUS 
devices that must never set the byte-offset bit call IOC6LOADUBAMAPA. 
Drivers for Q22-bus-only devices also call IOC6LOADUBAMAPA as there is 
no byte-offset bit in a Q22-bus map register. 


Both IOC$LOADUBAMAP and IJOC$LOADUBAMAPA clear the last map 
register. This last invalid register prevents a transfer overrun. 


Operating System Routines 
lIOCSMOVFRUSER, IOC$MOVFRUSER2 


IOCSMOVFRUSER, IOCSMOVFRUSER2 


Move a string from a user buffer to a system buffer. 





module BUFFERCTL 
input 
Location Contents 
RO Address of byte to be moved 
(IOCSMOVFRUSER2 only) 
R1 Address of driver's buffer 
R2 Number of bytes to move 
*R5 Address of UCB 
DPT$B_FLAGS Bit DPT$V_SVP set (causing a system page-table 
entry (SPTE) to be allocated to the driver) 
UCB$L_SVAPTE System virtual address of PTE that maps the first 
page of the buffer 
UCB$L_SVPN System virtual page number of SPTE allocated to 
driver 
UCB$W_BOFF Byte offset to start of transfer in page 
output 
None. 
synchronization The caller of IOC$MOVFRUSER or IOC6MOVFRUSER2 may be executing 
at fork IPL or above and must hold the corresponding fork lock in a VMS 
multiprocessing environment. Either routine returns control to its caller at the 
caller’s IPL. The caller retains any spin locks it held at the time of the call. 
DESCRIPTION  IOC$MOVFRUSER2 is useful for moving blocks of data in several pieces, 


each piece beginning within a page rather than on a page boundary. To 
begin, the driver calls IOC6MOVFRUSER. For each subsequent piece, the 
driver calls IOC6MOVFRUSER2. 


If an SPTE has not been allocated to the driver, these routines will cause an 
access violation when they attempt to refer to the location addressed by the 
contents of the field UCB$L_SVAPTE. (See the description of the DPTAB 
macro in Appendix B for information on how to allocate this SPTE.) 
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lIOCSMOVTOUSER, IOC$MOVTOUSER2 


IOCSMOVTOUSER, IOCSMOVTOUSER2 


Move a string from a system buffer to a user buffer. 





module BUFFERCTL 
input 
Location Contents 
RO Address of byte to be moved 
(IOCS6MOVTOUSER2 only) 
“RI Address of driver's buffer 
R2 Number of bytes to move 
R5 Address of UCB 
DPT$B_FLAGS Bit DPT$V_SVP set (causing a system page-table 
entry (SPTE) to be allocated to the driver) 
UCB$L_SVAPTE System virtual address of PTE that maps the first 
page of the buffer 
UCB$L_SVPN System virtual page number of SPTE allocated to 
driver 
UCB$W__BOFF Byte offset to start of transfer in page 
output 
None. 
synchronization The caller of IOC6MOVTOUSER or IOCSMOVTOUSER2 may be executing 
at fork IPL or above and must hold the corresponding fork lock in a VMS 
multiprocessing environment. Either routine returns control to its caller at the 
caller’s IPL. The caller retains any spin locks it held at the time of the call. 
DESCRIPTION  [I0C$MOVTOUSER? is useful for moving blocks of data in several pieces, 
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each piece beginning within a page rather than on a page boundary. To 
begin, the driver calls IOCS6MOVTOUSER. For each subsequent piece, the 
driver calls IOC6MOVTOUSER2. 


If an SPTE has not been allocated to the driver, these routines will cause an 
access violation when they attempt to refer to the location addressed by the 
contents of the field UCB$L_SVAPTE. (See the description of the DPTAB 
macro in Appendix B for information on how to allocate this SPTE.) 


Operating System Routines 
l|OCS$PURGDATAP 


lIOCSPURGDATAP 


Purges the buffered data path and logs memory errors that may have 
occurred during an I/O transfer. 





module [SYSLOA]LIOSUBxxx 

macro PURDPR 

input 
Location Contents 
R5 Address of UCB 

output 
Location Contents 
RO Bit O set if success, clear if failure 
R1 Contents of data path after purge 
R2 Address of start of the |/O bus map registers 
R3 Address of CRB 

synchronization The caller of IOC$PURGDATAP may be executing at fork IPL or above 
and must hold the corresponding fork lock in a VMS multiprocessing 
environment. It returns control to its caller at the caller’s IPL. The caller 
retains any spin locks it held at the time of the call. 

DESCRIPTION All device drivers that support DMA transfers, including those on VAX 


systems that have no buffered data paths (such as the MicroVAX 3600 series, 
MicroVAX II, and MicroVAX I), call IOC6PURGDATAP after a data transfer. 


IOC$PURGDATAP performs the following tasks: 


e Obtains the start of adapter register space using the following chain of 
pointers: 


UCB$L_CRB — CRB$L_INTD+VEC$L_ADP — ADP$L_CSR 
e Extracts the caller’s data path number (buffered or direct) from the CRB. 


e Purges the data path if it is a buffered data path. Note that a purge of a 
direct data path (data path 0) is legal and always results in success status. 


e Stores the contents of the data path register in R1. The driver’s register 
dumping routine writes this value to the error message buffer. 
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lIOCS$PURGDATAP 
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Clears any purge errors in the data path register. 
Places the appropriate return status in RO. 


Determines the base of UNIBUS or Q22-bus map registers and writes the 
value into R2. The driver’s register dumping routine writes this value to 
the error message buffer. 


In some machine implementations, checks for memory errors that might 
have occurred during the DMA operation and, if an error is detected, 
logs it. 


IOCSRELALTMAP 
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IOCSRELALTMAP 


Releases a set of O22-bus alternate map registers. 





module [SYSLOA]MAPSUBxxx 
macro RELALT 
input 
Location Contents 
R5 Address of UCB 
UCB$L_CRB Address of CRB 
CRB$L_INTD+ Address of ADP 
VECS$L ADP 
CRB$L_INTD+ Starting alternate map register number; VEC$V_ 
VEC$W_MAPALT ALTLOCK set indicates that alternate map 
registers have been permanently allocated to 
this controller 
CRB$L_INTD+ Number of allocated alternate map registers 
VEC$W_NUMALT 
ADP$L_MR2Q0FL Head of queue of UCBs waiting for alternate map 
registers 
ADP$W_MR2NREGAR, Alternate map register descriptor arrays 
ADP$W_MR2FREGAR, 
ADP$L_MR2ACTMDR 
output 
Location Contents 
RO SS$_NORMAL or SS$_SSFAIL 
R1, R2 Destroyed 
ADP$W_MR2NREGAR, Updated 
ADP$W_MR2FREGAR, 
ADP$L_MR2ACTMDR 
synchronization A driver fork process calls IOC$RELALTMAP at fork IPL, holding the 
corresponding fork lock in a VMS multiprocessing environment. 
A driver fork process calls IOC6RELALTMAP to release a previously-allocated 


DESCRIPTION 


set of Q22-bus alternate map registers (registers 496 to 8191) and update the 


alternate map register descriptor arrays in the ADP. IOC6RELMAPREG 
assumes that its caller is the current owner of the controller data channel. 
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IOC$RELALTMAP obtains the location and number of the allocated 
map registers from CRB$L_INTD+VEC$W_MAPALT and CRB$L_ 
INTD+VEC$W_NUMALT, respectively. If VEC$V_ALTLOCK is set in 
CRB$L_INTD+VEC$W_MAPALLT, the alternate map registers have been 
permanently allocated to the controller and IOC$RELALTMAP returns 
successfully to its caller. 


After adjusting the alternate map register descriptor arrays, 
IOC$RELALTMAP examines the alternate-map-register wait queue. If the 
queue is empty, IOC$RELALTMAP returns successfully to its caller. If the 
queue contains waiting fork processes, IOC6RELALTMAP dequeues the first 
process and calls IOC$ALOALTMAP to attempt to allocate the set of map 
registers it requires. 


If there are sufficient alternate map registers, IOCSRELALTMAP restores R3 
through R5 to the process and reactivates it. When this fork process returns 
control to IOC$RELALTMAP, IOC$RELALTMAP attempts to allocate map 
registers to the next waiting fork process. IOC6RELALTMAP continues to 
allocate map registers in this manner until the alternate-map-register wait 
queue is empty or it cannot satisfy the requirements of the process at the 
head of the queue. In the latter event, IOC$6RELALTMAP reinserts the fork 
process’s UCB in the queue and returns successfully to its caller. 


If the VAX system does not support alternate map registers, 
IOC$RELALTMAP exits with SS$_SSFAIL status. 


IOCS$RELCHAN 


Releases device ownership of all controller data channels. 


Operating System Routines 


IOCSRELCHAN 





module IOSUBNPAG 
macro RELCHAN 
input 
Location Contents 
R5 Address of UCB 
UCB$L_CRB Address of CRB 
CRB$L_LINK Address of secondary CRB 
CRB$B_MASK CRB$V_BSY set if the channel is busy 
CRB$L_INTD+VEC$L _IDB Address of IDB 
IDB$L_OWNER Address of UCB of channel owner 
CRB$L_WOFL Head of queue of UCBs waiting for the controller 
channel 
output 
Location Contents 
RO, R1, R2 Destroyed 
IDB$L__OWNER Cleared if no driver is waiting for the channel 
CRB$B_MASK CRB$V_BSY cleared if no driver is waiting for the 
channel 
synchronization — A driver fork process calls IOC$RELCHAN at fork IPL, holding the 
corresponding fork lock in a VMS multiprocessing environment. 
IOC$RELCHAN returns control to its caller after resuming execution of 
other fork processes waiting for a controller channel. 
DESCRIPTION A driver fork process calls IOC$RELCHAN to release all controller data 


channel assigned to a device; it calls IOC$RELSCHAN to release only the 


secondary data channel. 


If the channel wait queue contains waiting fork processes, IOC6RELCHAN 
dequeues a process, assigns the channel to that process, restores R3 and R5, 
moves the address of the CSR (IDB$L_CSR) into R4, and reactivates the 


suspended fork process. 
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IOC$RELDATAP | 


IOCS$RELDATAP 


Releases a UNIBUS adapter’s buffered data path. 





module IOSUBNPAG 
macro RELDPR 
input 
Location Contents 
R5 Address of UCB 
UCB$L_CRB Address of CRB 
CRB$L_INTD+ Address of ADP 
VEC$L_ADP 
CRB$L_INTD+ Data path specifier; VEC8V_PATHLOCK set if the 
VEC$B_DATAPATH data path has been permanently allocated to the 
controller 
ADP$L_DPOFL Head of queue of UCBs waiting for a UNIBUS 
adapter buffered data path 
ADP$W_DPBITMAP Data path bit map 
output 
Location Contents 
RO, R1, R2 Destroyed 
ADP$W_DPBITMAP Bit representing data path set if the path is not 
allocated to another driver fork process 
CRB$L_INTD+ Bits O through 4 cleared if the path is not 
VEC$B_DATAPATH permanently allocated 
synchronization A driver fork process calls IOC$RELDATAP at fork IPL, holding 
the corresponding fork lock in a VMS multiprocessing environment. 
IOC$RELDATAP returns control to its caller after resuming execution of 
any other fork processes waiting for a buffered data path. 
DESCRIPTION _ A driver fork process must own a UNIBUS buffered data path when it calls 
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IOC$RELDATAP. 


IOC$RELDATAP obtains the number of the allocated data path from bits 

0 through 4 of the data path specifier. If VEC$V_PATHLOCK is set in the 
specifier, the data path has been permanently allocated to the controller and 
IOC$RELDATAP returns to its caller. 


Operating System Routines 
lIOCS$RELDATAP 


If the data path wait queue contains waiting fork processes, IOC6RELDATAP 
dequeues the first process, allocates the data path to it, restores R3 through 
R5, and reactivates it. Otherwise, it marks the path available by setting the 
corresponding bit in the data path bit map (ADP$W_DPBITMAP), and returns 
to its caller. 


If the bit map has been corrupted, IOC6RELDATAP issues an INCONSTATE 
bugcheck. 
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lIOCSRELMAPREG 





lIOCSRELMAPREG 


Releases a set of UNIBUS map registers or a set of the first 496 Q22-bus 


map registers. 





module IOSUBNPAG 
macro RELMPR 
input 
Location Contents 
R5 Address of UCB 
UCB$L_CRB Address of CRB 
CRB$L_INTD+ Address of ADP 
VEC$L_ADP 
CRB$L_INTD+ Starting map register number; VEC$V_MAPLOCK 
VEC$W_MAPREG set indicates that map registers have been 
permanently allocated to this controller 
CRB$L _INTD+ Number of allocated map registers 
VEC$B_NUMREG 
ADP$L_MROFL Head of queue of UCBs waiting for map registers 
ADP$W_MRNREGARY, Map register descriptor arrays 
ADP$W_MRFREGARY, 
ADP$L_MRACTMDRS 
output 
Location Contents 
RO SS$_NORMAL or SS$_SSFAIL 
R1, R2 Destroyed 
ADP$W_MRNREGARY, Updated 
ADP$W_MRFREGARY, 
ADP$L_MRACTMDRS 
synchronization A driver fork process calls IOC$RELMAPREG at fork IPL, holding the 
corresponding fork lock in a VMS multiprocessing environment. 
A driver fork process calls IOC6RELMAPREG to release a previously- 


DESCRIPTION 


allocated set of UNIBUS map registers or a set of the first 496 Q22 bus map 


registers. IOCSRELMAPREG updates the alternate map register descriptor 
arrays in the ADP. IOC6RELMAPREG assumes that its caller is the current 
owner of the controller data channel. 
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lIOCSRELMAPREG 


IOC$RELMAPREG obtains the location and number of the allocated 

map registers from CRB$L_INTD+VEC$W_MAPREG and CRB$L— 
INTD+VEC$B_NUMREG, respectively. If VEC$6V_MAPLOCK is set in 
CRB$L_INTD+VEC$W_MAPREG, the map registers have been permanently 
allocated to the controller and IOC$6RELMAPREG returns successfully to its 
caller. 


After adjusting the map register descriptor arrays, IOC6RELMAPREG 
examines the standard-map-register wait queue. If the queue is empty, 
IOC$RELMAPREG returns successfully to its caller. If the queue contains 
waiting fork processes, IOC$SRELMAPREG dequeues the first process and 
calls IOC6ALOUBAMAP to attempt to allocate the set of map registers it 
requires. 


If there are sufficient map registers, IOC6RELMAPREG restores R3 through 
R5 to the process and reactivates it. When this fork process returns control to 
IOC$RELMAPREG, IOC$RELMAPREG attempts to allocate map registers to 
the next waiting fork process. IOC$6RELMAPREG continues to allocate map 
registers in this manner until the standard-map-register wait queue is empty 
or it cannot satisfy the requirements of the process at the head of the queue. 
In the latter event, IOC6RELMAPREG reinserts the fork process’s UCB in the 
queue and returns successfully to its caller. 
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IOCSRELSCHAN 


IOCSRELSCHAN 


Releases device ownership of only the secondary controller's data channel. 





module IOSUBNPAG 
macro RELSCHAN 
input 
Location Contents 
R5 Address of UCB 
UCB$L_CRB Address of CRB 
CRB$L_LINK Address of secondary CRB 
CRB$SB_MASK CRB$V_BSY set if the channel is busy 
CRB$L_INTD+VEC$L_IDB Address of IDB 
IDB$L__OWNER Address of UCB of channel owner 
CRB$L_WOFL Head of queue of UCBs waiting for the controller 
channel 
output 
Location Contents 
RO, R1, R2 Destroyed 
IDB$L__OWNER Cleared if no driver is waiting for the channel 
CRB$B_MASK CRB$V_BSY cleared if no driver is waiting for the 
channel 
synchronization A driver fork process calls IOC$RELSCHAN at fork IPL, holding 
the corresponding fork lock in a VMS multiprocessing environment. 
IOC$RELSCHAN returns control to its caller after resuming execution of 
other fork processes waiting for the secondary controller’s channel. 
DESCRIPTION = IOC$RELSCHAN releases a secondary controller’s data channel (for 
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instance, the MASSBUS adapter’s controller data channel). The caller retains 
ownership of the primary controller’s data channel. A driver fork process 
calls IOC6RELCHAN to release all controller data channels assigned to a 


device. 


If the secondary channel’s wait queue contains waiting fork processes, 
IOC$RELSCHAN dequeues a process, assigns the channel to that process, 
restores R3 through R5, and reactivates the suspended process. 


IOCSREQALTMAP 


Operating System Routines 


IOCSREQALTMAP 


Allocates sufficient Q22-bus alternate map registers to accommodate a 
DMA transfer and, if unavailable, places the requesting fork process in an 
alternate-map-register wait queue. 


module 


macro REQALT 


input 7 
Location 


R5 

OO0(SP) 

04(SP) 
UCB$W_BCNT 
UCB$W_BOFF 
UCBS$L_CRB 


CRB$L_INTD+ 
VEC$L_ADP 


CRB$L_INTD+ 
VECS$W_MAPALT 


ADP$W_MR2NREGAR, 
ADP$W_MR2FREGAR, 
ADP$L_MR2ACTMDR 


ADP$L_MR2QBL 


SYSLOA[MAPSUB]xxx 


Contents 

Address of UCB 

Return PC of caller 

Return PC of caller’s caller 
Transfer byte count 

Byte offset in page 
Address of CRB 

Address of ADP 


VEC$V_ALTLOCK set indicates that alternate 
map registers have been permanently allocated to 
this controller 


Alternate map register descriptor arrays 


Tail of queue of UCBs waiting for alternate map 
registers 


Operating System Routines 


lIOCSREQALTMAP 


output 


synchronization 


Location 
RO 
R1 
R2 


CRBSL_INTD+ 
VECS$W_NUMALT 


CRB$L_INTD+ 
VEC$W_MAPALT 


ADP$W_MR2NREGAR, 
ADP$W_MR2FREGAR, 
ADP$L_MR2ACTMDR 


ADP$L_—MR2QBL 
UCB$L_FR3 
UCB$L_FR4 
UCBSL_FPC 


Contents 

SS$_NORMAL or SS$_SSFAIL 

Destroyed 

Address of ADP 

Number of alternate map registers allocated 


Starting alternate map register number 


Updated 


Updated 
R3 of caller 
R4 of caller 
OO(SP) 


A driver fork process calls IOC$REQALTMAP at fork IPL, holding the 
corresponding fork lock in a VMS multiprocessing environment. 





DESCRIPTION 
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A driver fork process calls IOC6REQALTMAP to allocate a contiguous set of 
Q22 bus alternate map registers (registers 496 to 8191) to service the DMA 
transfer described by UCB$W_BCNT and UCB$W_BOFF. IOC$REQALTMAP 
calls IOC6ALOALTMAP. 


If alternate map registers have been permanently allocated to the controller, 
IOC$REQALTMAFP returns successfully to its caller without allocating map 
registers. Otherwise, it searches the alternate map register descriptor arrays 
for the required number of map registers. 


IOC$ALOALTMAP determines the required number of alternate map 
registers from the contents of UCB$W_BOFF and UCB$W_BCNT. It allocates 
one extra map register; this register is marked invalid when the driver fork 
process subsequently calls IOC6LOADALTMAP, thus preventing a transfer 
overrun. If an odd number of map registers is required, IOC6ALOALTMAP 
rounds this value up to an even multiple. 


If sufficient alternate map registers are available, IOC6REQALTMAP assigns 
them to its caller, records the allocation in the ADP and CRB, and returns 
successfully to its caller. 


If IOCSREQALTMAP cannot allocate a sufficient number of contiguous map 
registers, it saves process context by placing the contents of R3, R4, and the 

PC into the UCB fork block and the UCB into the alternate-map-register wait 
queue (ADP$L_MR2QBL). It then returns to its caller’s caller. 


If the VAX system does not support alternate map registers, 
IOC$REQALTMAP exits with SS$_SSFAIL status. 


lIOCSREQCOM 


Operating System Routines 


lIOCS$REQCOM 


Completes an 1/O operation on a device unit, requests I/O postprocessing 
of the current request, and starts the next I/O request waiting for the 


device. 


module IOSUBNPAG 


macro REQCOM 


input 
Location 


RO 
R1 
R5 
UCB$L_STS 


UCBSB_ERTCNT 
UCBSB_ERTMAX 
UCB$L_EMB 
UCBS$L _IRP 
UCB$B_DEVCLASS 


UCB$L_IOQFL 
CPU$L_PSBL 


output 


Location 
RO through R3 


IRP$L_IOST 1 
IRP$L_IOST2 
UCB$L__OPCNT 
UCBSL_IOOFL 
EMB$W_DV_STS 
EMB$B_DV_ERTCNT 
EMB$B_DV_ERTCNT+1 
EMB$Q__DV_IOSB 
UCBSL_STS 
CPU$L_PSBL 


Contents 

First longword of I/O status. 
Second longword of I/O status. 
Address of UCB. 


UCB$V_ERLOGIP set if error logging is in 
progress. 


Final error count. 

Maximum error retry count. 
Address of error message buffer. 
Address of IRP. 


DC$_DISK and DC$_TAPE devices are subject to 
mount verification checks. 


Device unit’s pending-I|/O queue. 


Tail of local processor's |/O postprocessing 
queue. 


Contents 


Destroyed. Other registers (used by the driver's 
start-1/O routine) are destroyed if IOCSINITIATE 
is called. 


First longword of |/O status. 

Second longword of I/O status. 
Incremented. 

Updated. 

UCBSW_STS. 

UCB$B_ERTCNT. 

UCB$B_ERTMAX. 

Quadword of I/O status. 

UCB$V_BSY and UCB$V_ERLOGIP cleared. 
Updated. 


C-91 


Operating System Routines 


lOCSREQCOM 


synchronization A driver fork process calls IOC$REQCOM at fork IPL, holding the 
corresponding fork lock in a VMS multiprocessing environment. 
IOC$REQCOM transfers control to IOC$RELCHAN. If the fork process 
calls IOC$6REQCOM by means of the REQCOM macro (or a JMP instruction), 
IOC$RELCHAN returns control to the caller of the driver fork process (for 
instance, the fork dispatcher). 





DESCRIPTION _ A driver fork process calls this routine after a device I/O operation and all 
device-dependent processing of an I/O request is complete. 


IOC$REQCOM performs the following tasks: 


If error logging is in progress for the device (as indicated by UCB$V_ 
ERLOGIP in UCB$L_STS), writes into the error message buffer the status 
of the device unit, the error retry count for the transfer, the maximum 
error retry count for the driver, and the final status of the I/O operation. 
It then releases the error message buffer by calling ERLGRELEASEMB. 


Increments the device unit’s operations count (UCB$L_OPCNT). 


If UCB$B_DEVCLASS specifies a disk device (DC$_DISK) or tape device 
(DC$_TAPE) and error status is reported, performs a set of checks to 
determine if mount verification is necessary. Tape end-of-file errors 
(SS$_ENDOFFILE) are exempt from these checks. For a tape device with 
success status, checks to determine if CRC must be generated. 


Writes final I/O status (RO and R1) into IRP$6L_IOST1 and IRP$L— 
IOST2. 


Inserts the IRP into the local processor’s I/O postprocessing queue 
headed by CPU$L_PSBL. 


Requests a software interrupt from the local processor at IPL$_IOPOST. 


Attempts to remove an IRP from the device’s pending-I/O queue (at 
UCB$L_IOQEL). If successful, it transfers control to IOC$INITIATE to 
begin driver processing of this I/O request. If the queue is empty, it 
clears the unit busy bit (UCB$V_BSY in UCB$L_STS) to indicate that the 
device is idle. 


Exits by transferring control to IOC$6RELCHAN. 


Operating System Routines 
IOCS$REQDATAP, IOC$REQDATAPNW 


IOCSREQDATAP, IOCSREQDATAPNW 


Request a UNIBUS adapter buffered data path and, optionally, if no path is 
available, place process in data-path wait queue. 


module IOSUBNPAG 
macro REQDPR 
input 
Location Contents 
R5 Address of UCB 
OO(SP) Return PC of caller 
04(SP) Return PC of caller’s caller 
UCB$L_CRB Address of CRB 
UCB$L_CRB Address of CRB 
CRB$L_INTD+ Address of ADP 
VECS$L_—ADP 
CRB$L_INTD+ Data path specifier; VEC$V_PATHLOCK set if 
VEC$B_DATAPATH the data path is permanently allocated to the 
controller 
ADP$W_DPBITMAP Data path bit map 
output 
Location Contents 
RO SS$_NORMAL or bit O set (indicating error 
status) 
CRB$L_INTD+ Data path specifier 


synchronization 


VEC$B_DATAPATH 
ADP$W_DPBITMAP 


Bit corresponding to allocated data path cleared 


A driver fork process calls IOC6REQDATAP or IOC$6REQDATAPNW at 
fork IPL, holding the corresponding fork lock in a VMS multiprocessing 


environment. 





DESCRIPTION 


A driver fork process calls IOC6REQDATAP or IOC6REQDATAPNW to 
request a UNIBUS adapter buffered data path for a DMA transfer. 


If a buffered data path is already permanently allocated to the controller, 
IOC$REQDATAP or IOC$REQDATAPNW returns successfully to its caller 
without allocating a data path. Otherwise, it searches the data path bit map 
for the first available data path. 


Operating System Routines 
IOC$REQDATAP, IOC$REQDATAPNW 
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If IOC6REQDATAP or IOC$REQDATAPNW locates a free data path, it writes 
the data path number into CRB$L_INTD+VEC$B_DATAPATH, updates 

the data path bit map (ADP$W_DPBITMAP), and returns successfully to its 
caller. If the bit map has been corrupted, the routine issues an INCONSTATE 
bugcheck. 


If IOC$6REQDATAP cannot allocate a data path, it saves process context 
by placing the contents of R3, R4 and the PC into the UCB fork block and 
the UCB into the data-path wait queue (ADP$L_DPQBL). It then returns 
to its caller’s caller. By contrast, if IOCS6REQDATAPNW cannot allocate a 
data path, it returns immediately to its caller with the low bit in RO clear, 
indicating an error. 


When called from a driver executing in a VAX system that does not provide 
buffered data paths, IOC$REQDATAP and IOC$REQDATAPNW return 
control after examining the data path bit map in the ADP. 


lIOCSREQMAPREG 


Operating System Routines 


IOCSREQMAPREG 


Allocates sufficient UNIBUS map registers or a sufficient number of the 
first 496 Q22-bus map registers to accommodate a DMA transfer and, if 
unavailable, places process in standard-map-register wait queue. 


module IOSUBNPAG 


macro REQMPR 


input 
Location 


R5 

O0(SP) 

04(SP) 
UCB$W_BCNT 
UCB$W_.BOFF 
UCB$L_CRB 


CRB$L_INTD+ 
VEC$L_ADP 


CRBSL_INTD+ 
VEC$W_MAPREG 


ADP$W_MRNREGARY, 
ADP$W_MRFREGARY, 


ADP$L_MRACTMDRS 
ADP$L_—MROBL 


Contents 
Address of UCB 


Return PC of caller 


Return PC of caller’s caller 
Transfer byte count 

Byte offset in page 
Address of CRB 

Address of ADP 


VEC$V_MAPLOCK set indicates that map 
registers have been permanently allocated to 
this controller 


Map register descriptor arrays 


Tail of queue of UCBs waiting for map registers 
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lIOCSREQMAPREG 


output 


synchronization 


Location 
RO 
R1 
R2 


CRB$L_INTD+ 
VEC$B_NUMREG 


CRBSL_INTD+ 
VEC$W_MAPREG 


ADP$W_MRNREGARY, 
ADP$W_MRFREGARY, 
ADP$L_MRACTMDRS 


ADP$L_MROBL 
UCB$L_FR3 
UCBS$L_FR4 
UCB$L_FPC 


Contents 

SS$_NORMAL 

Destroyed 

Address of ADP 

Number of map registers allocated 


Starting map register number 
Updated 

Updated 

R3 of caller 


R4 of caller 
OO(SP) 


A driver fork process calls IOC6REQMAPREG at fork IPL, holding the 
corresponding fork lock in a VMS multiprocessing environment. 





DESCRIPTION 


C-96 


A driver fork process calls IOC6REQMAPREG to allocate a contiguous set 
of UNIBUS map registers or a set of the first 496 Q22-bus map registers to 
service the DMA transfer described by UCBSW_BCNT and UCB$W_BOFF. 
IOC$REQMAPREG calls IOCSALOUBAMAP. 


If map registers have been permanently allocated to the controller, 
IOC$REQMAPREG returns successfully to its caller without allocating map 
registers. Otherwise, it searches the map register descriptor arrays for the 
required number of map registers. . 


IOC$ALOUBAMAP determines the required number of map registers from 
the contents of UCB$W_BOFF and UCB$W_BCNT. It allocates one extra 
map register; this register is marked invalid when the driver fork process 
subsequently calls IOC$LOADUBAMAP, thus preventing a transfer overrun. 
If an odd number of map registers is required, IOC6ALOUBAMAP rounds 
this value up to an even multiple. 


If sufficient map registers are available, IOC6REQMAPREG assigns them to 
its caller, records the allocation in the ADP and CRB, and returns successfully 


to its caller. 


If IOC6REQMAPREG cannot allocate a sufficient number of contiguous map 
registers, it saves process context by placing the contents of R3, R4, and the 
PC into the UCB fork block and R5 into the standard-map-register wait queue 
(ADP$L_MRQBL). It then returns to its caller’s caller. 


Operating System Routines 


IOCSREQPCHANH, IOCSREQPCHANL, IOCSREQSCHANH, IOCSREQSCHANL 


IOCSREQPCHANH, IOC$REQPCHANL, 
IOCSREQSCHANH, IOC$REQSCHANL 


Request a controller's primary or secondary data channel and, if 
unavailable, place process in channel wait queue. 


module 


macro 


input 


output 


synchronization 


IOSUBNPAG 


REQPCHAN, REQSCHAN 


Location 

R5 

00(SP) 
04(SP) 
UCB$L_CRB 
CRB$L_LINK 


CRB$B_MASK 
CRB$L_INTD+VEC$L _IDB 
CRB$L_WOFL 


CRB$L_WOBL 


IDB$L_CSR 


Location 

RO, R1, R2 

R4 
IDB$L__OWNER 
CRB$L_WOFL 
CRB$L_WOBL 


Contents 

Address of UCB 

Return PC of caller 

Return PC of caller's caller 
Address of CRB 


Address of secondary CRB (IOC$REQSCHANH 
and IOC$REQSCHANL only) 


CRB$V_BSY set if the channel is busy 
Address of IDB 


Head of queue of UCBs waiting for the controller 
channel 


Tail of queue of UCBs waiting for the controller 
channel 


Address of device CSR 


Contents 

Destroyed 

Address of device CSR 
Address of UCB 
Updated 

Updated 


A driver fork process calls IOCSREQPCHANH, IOC$REQPCHANL, 
IOC$REQSCHANH, or IOC$REQSCHANL holding the corresponding fork 
lock in a VMS multiprocessing environment. 


Operating System Routines 
lIOC$REQPCHANH, IOC$REQPCHANL, IOC$REQSCHANH, IOC$REQSCHANL 





DESCRIPTION 
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A driver fork process calls IOC6REQPCHANH or IOC$REQPCHANL 

to acquire ownership of the primary controller’s data channel; it calls 
IOC$REQSCHANH or IOC$REQSCHANL to request the secondary 
controller’s data channel (for instance, the MASSBUS adapter’s controller 
data channel). 


Each routine examines CRB$V_BSY in CRB$B_MASK. If the selected 
controller’s data channel is idle, the routine grants the channel to the 
fork process, placing its UCB address in IDB$L_OWNER and returning 
successfully with the device’s CSR address in R4. 


If the data channel is busy, the routine saves process context by placing 

the contents of R3 and the PC into the UCB fork block. (Note that 
IOC$RELCHAN moves the contents of IDB$L—CSR into R4 before 
resuming execution of a waiting fork process.) IOC6REQPCHANH and 
IOC$REQSCHANH then insert the UCB at the head of the channel wait 
queue (CRB$L_WQEL); IOC$REQPCHANL and IOC$REQSCHANL insert 
the UCB at the tail of the queue (CRB$L_WOQBL). Finally, the routine returns 
control to its caller’s caller. 


Operating System Routines 
lIOC$RETURN 


IOCSRETURN 


Returns to its caller. 


module None. 
input 
P None. 
output 
None. 


synchronization JOC$RETURN executes at its caller’s IPL and returns control to the caller at 
that IPL. 





DESCRIPTION = IOC$RETURN is a universal executive routine vector in the fixed portion 
of the VMS executive. It contains a single RSB instruction. When a driver 
invokes the DDTAB macro, the macro writes the address of IOC6RETURN 
into routine address fields of the DDT that are not supplied in the macro 
invocation. 
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Operating System Routines 
IOC$VERIFYCHAN 


IOCSVERIFYCHAN 


Verifies an |/O channel number and translates it to a CCB address. 





module IOSUBPAGD 

input 
Location Contents 
RO . Channel number (in low word) 
CTL$SGL_CCBBASE Base address of process CCB table 
CCB$B_AMOD Access mode (plus 1) of process owning the 

channel 

output 
Location Contents 
RO SS$_NORMAL, SS$_IVCHAN, or SS$_NOPRIV 
R1 Address of CCB 
R2 Channel index number 
R3 Destroyed 

synchronization Because IOC$VERIFYCHAN gains access to information stored in user 
process virtual address space, it should only be called from code originating 
at IPL$_ASTDEL or below. 

DESCRIPTION Drivers call IOC$VERIFYCHAN to validate a user-supplied channel number, 
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construct a channel index, and obtain the address of the CCB to which the 
channel number points. . 


If the channel number is invalid or zero, or if the channel is unowned, 
IOC$VERIFYCHAN returns SS$_IVCHAN status to its caller. 


If the access mode of the current process is less privileged than that indicated 
in CCB$B_AMOD, IOC$VERIFYCHAN returns SS$_NOPRIV status to its 
caller with the address of the CCB in R1. 


Otherwise, IOC$VERIFYCHAN returns successfully to its caller with the 
address of the CCB in R1. 


Operating System Routines 


IOCSWFIKPCH, IOCS$WFIRLCH 


IOCSWFIKPCH, IOCS$WFIRLCH 


module 


macro 


input 


output 


synchronization 


Suspend a driver fork thread and fold its context into a fork block in 
anticipation of a device interrupt or timeout. 


IOSUBNPAG 


WFIKPCH, WFIRLCH 


Location 
R5 
OO(SP) 


O04(SP) 
08(SP) 


12(SP) 


EXE$GL_ABSTIM 


Location 
UCB$L_DUETIM 
UCB$V_INT 


UCB$V_TIM 
UCB$V_TIMOUT 
UCBS$L_FR3 
UCB$L_FR4 
UCBS$L_FPC 


Contents 
Address of UCB 


Address following the JSB to IOC$WFIKPCH or 
lOC$WFIRLCH 


Timeout value in seconds 


IPL to which to lower before returning to the 
caller's caller 


Return PC of caller's caller 


Absolute time 


Contents 
Sum of timeout value and EXE$GL_ABSTIM 


Set to indicate that interrupts are expected on the 
device 


Set to indicate device I/O is being timed 
Cleared to indicate that unit is not timed out 
R3 

R4 

OO(SP)+2 


When it is called, IOC6WFIKPCH or IOC$WFIRLCH assumes that the local 
processor has obtained the appropriate synchronization with the device 


database: 


¢ Ina uniprocessing environment, the processor must be executing at device 


IPL or above. 


¢ Ina multiprocessing environment, the processor must own the appropriate 
device lock, as recorded in the unit control block (UCB$L_-DLCK) of the 
device unit from which the interrupt is expected. This requirement also 
presumes that the local processor is executing at the device IPL associated 


with the lock. 
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IOCSWFIKPCH, IOC$WFIRLCH 
Before exiting, IOCSWFIKPCH or IOC$WFIRLCH achieves the following 
synchronization: 
¢ Ina uniprocessing environment, it lowers the local processor’s IPL to the 
IPL saved on the stack. 
¢ Ina multiprocessing environment, it conditionally releases the device lock, 
so that if the caller of the driver fork thread (the caller’s caller) previously 
owned the device lock, it will continue to hold it when the routine exits. 
IOC$WFIKPCH or IOC$WFIRLCH also lowers the local processor s IPL 
to the IPL saved on the stack. 
DESCRIPTION A driver fork process calls IOC$WFIKPCH to wait for an interrupt while 
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keeping ownership of the controller’s data channel; IOC6WFIRLCH, by 
contrast, releases the channel. 


Either routine performs the following operations: 


e Adds 2 to the address on the top of the stack to determine the address of 
the next instruction in the driver fork thread after the invocation of the 
WFIKPCH or WFIRLCH macro. (Note that the macro places the relative 
offset to the timeout handling routine in the word following the JSB to 
IOC$WFIKPCH or IOCSWFIRLCH.) It pops this address into the UCB 
fork block (UCB$L_FPC) so that the driver’s interrupt service routine can 
resume execution of the driver fork thread with a JSB instruction. 


e¢ Pops R3 and R4 from the top of the stack into the UCB fork block. 
e Sets UCB$V_INT to indicate an expected interrupt from the device unit. 


e Sets UCB$V_TIM to indicate that VMS should check for timeouts from 
the device unit. 


e Determines the timeout due time from the timeout value, now at the top 
of the stack, and EXE$GL_ABSTIM, and stores the result in UCB$L_ 
DUETIM. 


e Clears UCB$V_TIMOUT to indicate that the unit has not timed out. 


e¢ Ina multiprocessing environment, issues a DEVICEUNLOCK to 
conditionally release the device lock associated with the device unit and 
to lower IPL to the IPL saved on the stack. These actions presume that 
the DEVICELOCK macro has been issued prior to the wait-for-interrupt 
invocation. 


e Returns to the caller of the driver fork thread (that is, its caller’s caller) 
whose address is now at the top of the stack. 


In the course of processing, IOC6WFIKPCH or IOC$WFIRLCH explicitly 
removes the longwords at 00(SP) through 08(SP) from the stack and implicitly 
removes the longword at 12(SP) by exiting with an RSB instruction. 


Note that IOC6WFIRLCH exits by transferring control to IOC$6RELCHAN. 
IOC$RELCHAN releases the controller data channel and executes the RSB 
instruction. Because the release of the channel occurs at fork IPL, an interrupt 
service routine cannot reliably distinguish between operations initiated by 

IOC$WFIKPCH and IOC$WFIRLCH by examining the ownership of the CRB. 


Operating System Routines 
LDRSALLOC_PT 


LDRSALLOC_PT 


Allocates the specified number of system page-table entries (SPTEs). 





module PTALLOC 
input 
Location Contents 
R2 Number of SPTEs to be allocated 
LDRSGL_SPTBASE Base of system page table 
LDR$SGL_FREE_PT Offset to first free SPTE 
output 
Location Contents 
RO SS$_NORMAL, SS$_INSFSPTS, or SS$_ 
BADPARAM 
R1 Address of first allocated SPTE 
R2 Number of allocated system page-table entries 
synchronization Because LDR$ALLOC_PT executes at IPL$_SYNCH and obtains the 
MMG spin lock in a VMS multiprocessing environment, its caller cannot 
be executing above IPL$_SYNCH or hold any higher ranked spin locks. 
(For instance, a driver fork process executing at IPL$_SYNCH holding the 
IOLOCK8 fork lock can call LDR$ALLOC_PT.) LDRSALLOC_PT returns 
control to its caller at the caller’s IPL. The caller retains any spin locks it held 
at the time of the call. 
DESCRIPTION LDR$ALLOC_PT allocates the number of system page-table entries (SPTEs) 


specified in R2. LDR$ALLOC_PT adjusts the pool of free SPTEs to reflect the 
allocation of the SPTEs. 


A generic VAXBI device driver calls LDRS6ALLOC_PT if it must map the 
device’s node window space. It is the caller’s responsibility to fill in each 
allocated SPTE with a page-frame number (PFN), set its valid bit, and 
otherwise initialize it. 


If R2 contains a zero, LDR$ALLOC_PT returns SS$_.BADPARAM status in 
RO and clears R1. If there are no free SPTEs, it returns SS$_INSFSPTS status 
to its caller. 
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Operating System Routines 
LDR$DEALLOC_PT 


LDR$DEALLOC_PT 


Deallocates the specified system page-table entries (SPTEs). 





module PTALLOC 

input 
Location Contents 
R1 Address of first SPTE to be deallocated 
R2 Number of SPTEs to be deallocated 

| LDR$GL_SPTBASE Base of system page table 

LDRSGL_FREE_PT Offset to first free SPTE 

output 
Location Contents 
RO SS$_NORMAL, SS$_BADPARAM, or LOADER$_ 

PTE_NOT_EMPTY 

R1 Address of first allocated SPTE 
R2 Destroyed 

synchronization Because LDR$DEALLOC_PT executes at IPL$_SYNCH and obtains the 
MMG spin lock in a VMS multiprocessing environment, its caller cannot 
be executing above IPL$_SYNCH or hold any higher ranked spin locks. 
(For instance, a driver fork process executing at IPL$_SYNCH holding the 
IOLOCK8 fork lock can call LDRSDEALLOC_PT.) LDRS{DEALLOC_PT 
returns control to its caller at the caller’s IPL. The caller retains any spin locks 
it held at the time of the call. 

DESCRIPTION LDR$DEALLOC_PT deallocates the number of system page-table entries 


(SPTEs) specified in R2, starting at the one indicated by the contents of R1. 
LDR$DEALLOC_PT adjusts the pool of free SPTEs to reflect the addition of 
the deallocated SPTEs. 


If R2 contains a zero, LDR$DEALLOC_PT returns SS$¢_BADPARAM status 
in RO and clears R1. 


It is the caller’s responsibility to ensure that the SPTEs to be deallocated are 
empty.” If they are not, LDR$DEALLOC_PT returns LOADER$_PTE_NOT_ 
EMPTY status in RO. | 


> Modifications to valid SPTEs require that these SPTEs be flushed from the system’s translation buffers. See the 
description of the INVALIDATE_TB macro in Appendix B. 
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MMG$UNLOCK 


MMGS$UNLOCK 


module 


input 


output 


synchronization 


Unlocks process pages previously locked for a direct-|/O operation. 


IOLOCK 

Location Contents 

R1 Number of buffer pages to unlock 

R3 System virtual address of PTE for the first buffer 
page 

None. 


Because MMG$UNLOCK raises IPL to IPL$_SYNCH, and obtains the 
MMG spin lock in a VMS multiprocessing environment, its caller cannot 
be executing above IPL$_SYNCH or hold any higher ranked spin locks. 
MMGS$UNLOCK returns control to its caller at the caller’s IPL. The caller 
retains any spin locks it held at the time of the call. 





DESCRIPTION 


Drivers rarely use MMG$UNLOCK. At the completion of a direct-I/O 
transfer, IOC$IOPOST automatically unlocks the pages of both the user 
buffer and any additional buffers specified in region 1 (if defined) and region 
2 (if defined) for all the IRPEs linked to the packet undergoing completion 
processing. . 


However, driver FDT routines do use MMG$UNLOCK when an attempt 

to lock IRPE buffers for a direct-I/O transfer fails. The buffer-locking 
routines called by such a driver—EXE$READLOCKR, EXE$WRITELOCKR, 
and EXE$MODIFYLOCKR—all perform coroutine calls back to the driver 

if an error occurs. When called as a coroutine, the driver must unlock all 
previously locked regions using MMG$UNLOCK, and deallocate the IRPE 
(using EXE{DEANONPAGED), before returning to the buffer-locking routine. 
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Operating System Routines 


SMPS$ACOQNOIPL 


SMPS$ACOQNOIPL 


Acquires a device lock, assuming the local processor is already running at 
the IPL appropriate for acquisition of the lock. 





module SPINLOCKS 
macro DEVICELOCK 
input 
Location Contents 
RO Address of device lock 
output 
Location Contents 
RO Address of device lock 
synchronization Upon entry, the local processor must be executing at the synchronization IPL 
of the device lock, as it is, for instance, when responding to a device interrupt. 
SMP$ACQNOIPL exits with the IPL unchanged and the device lock held. 
DESCRIPTION The DEVICELOCK macro calls SMP$ACQNOIPL when NOSETIPL is 
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specified as its condition argument. 


SMP$ACQNOIPL attempts to acquire the requested device lock, allowing the 
acquisition to succeed if the local processor already holds the lock or if the 
lock is unowned. 


If the lock is unowned, the routine increments by 1 a counter that records the 
acquisition level. Each additional (or nested) acquisition of this lock by the 
owning processor again increments this counter. 


If the lock is owned by another processor, the local processor spin waits until 
the lock is released. 


Operating System Routines 
SMP$ACQUIRE 


SMPS$ACQUIRE 


Acquires a fork lock or spin lock and enforces the appropriate IPL 
synchronization on the local processor. 





module SPINLOCKS 

macro FORKLOCK, LOCK 

input 
Location Contents 
RO Fork lock or spin lock index 

output 
Location Contents 
RO Fork lock or spin lock index 

synchronization When calling SMP$ACQUIRE, the local processor should be executing at 
an IPL less than or equal to the synchronization IPL of the lock. The 
routine, if necessary, immediately raises IPL to the synchronization IPL of 
the lock. Violations of IPL synchronization in a full-checking multiprocessing 
environment result in a SPLIPLHIGH bugcheck. 
In a full-checking multiprocessing environment, if it must spin wait for 
the requested lock to be released by another processor, SMP$ACQUIRE 
temporarily restores the original IPL for the duration of the wait. If the 
original IPL was less than IPL$_RESCHED, the spin wait occurs at IPL$_ 
RESCHED. 
SMP$ACQUIRE exits with IPL at the synchronization IPL of the lock and the 
fork lock or spin lock held. 

DESCRIPTION — The FORKLOCK and LOCK macros call SMP$ACQUIRE. 


In a full-checking multiprocessing environment, SMP$ACQUIRE, having 
ensured that IPL has been set to the lock’s synchronization IPL, verifies that 
the local processor does not currently hold any higher-ranked locks. If a 
higher-ranked lock is held, SMP$ACQUIRE issues an SPLACQERR bugcheck. 


Otherwise SMP$ACQUIRE attempts to acquire the requested lock, allowing 


the acquisition to succeed if the local processor already holds the lock or if 
the lock is unowned. 


If the lock is unowned, the routine increments by 1 a counter that records the 
acquisition level. Each additional (or nested) acquisition of this lock by the 
owning processor again increments this counter. 


If the lock is owned by another processor, the local processor spin waits until 
the lock is released. 
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SMP$ACQUIREL 


SMP$ACQUIREL 


module 


macro 


input 


output 


synchronization 


Acquires-a device lock and enforces the appropriate IPL synchronization 
on the local processor. 


SPINLOCKS 

DEVICELOCK 

Location Contents 

RO Address of device lock 
Location Contents 

RO Address of device lock 


When calling SMP$ACQUIREL, the local processor should be executing at 
an IPL less than or equal to the synchronization IPL of the device lock. The 
routine, if necessary, immediately raises IPL to the synchronization IPL of 
the device lock. Violations of IPL synchronization result in a SPLIPLHIGH 
bugcheck if full-checking multiprocessing is enabled. 


In a full-checking multiprocessing environment, if it must spin wait for 
the requested lock to be released by another processor, SMP$ACQUIREL 
temporarily restores the original IPL for the duration of the wait. If 

the original IPL was less than IPL$_RESCHED, the spin wait occurs at 
IPL$_RESCHED. SMP$ACQUIREL exits with IPL at the device lock’s 
synchronization IPL and the device lock held. 





DESCRIPTION 
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The DEVICELOCK macro calls SMP$ACQUIREL when NOSETIPL is not 
specified as its condition argument. 


SMP$ACQUIREL, having ensured that IPL has been set to the device lock’s 
synchronization IPL, attempts to acquire the requested device lock, allowing 
the acquisition to succeed if the local processor already holds the lock or if 
the lock is unowned. 


If the lock is unowned, the routine increments by 1 a counter that records the 
acquisition level. Each additional (or nested) acquisition of this lock by the 
owning processor again increments this counter. 


If the lock is owned by another processor, the local processor spin waits until 
the lock is released. 


Operating System Routines 
SMP$RELEASE 


SMP$RELEASE 


module 


macro 


input 


output 


synchronization 


Releases all acquisitions of a fork lock or spin lock by the local processor 
and makes the lock available for acquisition by other processors. 


SPINLOCKS 


FORKUNLOCK, UNLOCK 


Location Contents 
RO Fork lock or spin lock index 
Location Contents 
RO Fork lock or spin lock index 


Upon entry, the local processor must be executing at or above the IPL at 
which the lock was originally obtained. This IPL must be greater than IPL$_ 
ASTDEL. Violations of IPL synchronization in a full-checking multiprocessing 
environment result in a SPLIPLLOW bugcheck. At exit, IPL is unchanged 
and the lock is released. 





DESCRIPTION 


The FORKUNLOCK and UNLOCK macros call SMP$RELEASE when the 
condition=RESTORE argument is not specified. 


SMPS$RELEASE first verifies that the local processor owns the specified 
lock. If this is not the case, the procedure issues an SPLRELERR bugcheck. 
Otherwise, SMP$RELEASE initializes the ownership count of the lock and 
releases the lock. 
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SMP$RELEASEL 


SMP$RELEASEL 


Releases all acquisitions of a device lock by the local processor and makes 
the lock available for acquisition by other processors. 





module SPINLOCKS 

macro DEVICEUNLOCK 

input 
Location Contents 
RO Address of device lock 

output 
Location Contents 
RO Address of device lock 

synchronization Upon entry, the local processor must be executing at or above the IPL at 
which the device lock was originally obtained. This IPL must be greater 
than IPL$_ASTDEL. Violations of IPL synchronization in a full-checking 
multiprocessing environment result in a SPLIPLLOW bugcheck. At exit, IPL. 
is unchanged and the device lock is released. 

DESCRIPTION —= The DEVICEUNLOCK macro calls SMP$RELEASEL when the 
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condition=RESTORE argument is not specified. 


SMP$RELEASEL first verifies that the local processor owns the specified 
device lock. If this is not the case, the procedure issues an SPLRELERR 
bugcheck. Otherwise, SMP$RELEASEL initializes the ownership count of the 
device lock and releases the lock. 


Operating System Routines 
SMPS$RESTORE 


SMP$RESTORE 


Releases a single acquisition of a fork lock or spin lock held by the local 
processor. 








module SPINLOCKS 
macro FORKUNLOCK, UNLOCK 
input 
Location Contents 
RO Fork lock or spin lock index 
output 
Location Contents 
RO Fork lock or spin lock index 
synchronization Upon entry, the local processor must be executing at or above the IPL at 
which the lock was originally obtained. This IPL must be greater than IPL$_ 
ASTDEL. Violations of IPL synchronization in a full-checking multiprocessing 
environment result in a SPLIPLLOW bugcheck. At exit, IPL is unchanged 
and the lock may or may not be still held. 
DESCRIPTION ~ The FORKUNLOCK and UNLOCK macros call SMP$RESTORE when 


RESTORE is specified as the condition argument. 


SMP$RESTORE first verifies that the local processor owns the specified 
lock. If this is not the case, the procedure issues an SPLRSTERR bugcheck. 
Otherwise, SMP$RESTORE proceeds to decrement the ownership count of 
the lock. If the ownership count of the lock drops to its initial state, the 
procedure releases the lock and makes it available to other processors. 
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SMPS$RESTOREL 


SMPS$RESTOREL 


Releases a single acquisition of a device lock held by the local processor. 





module SPINLOCKS 
macro DEVICEUNLOCK 
input 
Location Contents 
RO Address of device lock 
output 
Location Contents 
RO | Address of device lock 
synchronization Upon entry, the local processor must be executing at or above the IPL at 
which the device lock was originally obtained. This IPL must be greater 
than IPL$_ASTDEL. Violations of IPL synchronization in a full-checking 
multiprocessing environment result in a SPLIPLLOW bugcheck. At exit, IPL 
is unchanged and the device lock may or may not be still held. 
DESCRIPTION = The DEVICEUNLOCK macro calls SMP$RESTOREL when RESTORE is 
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specified as its condition argument. 


SMP$RESTOREL first verifies that the local processor owns the specified 
device lock. If this is not the case, the procedure issues an SPLRSTERR 
bugcheck. Otherwise, SMP$RESTOREL proceeds to decrement the ownership 
count of the device lock. If the ownership count of the device lock drops to 
its initial state, the procedure releases the lock and makes it available to other 
processors. 


[. Device Driver Entry Points 


This appendix describes the entry points VMS uses to activate a device driver. 


Device Driver Entry Points 
Alternate Start-1/O Routine 


Alternate Start-1/O Routine 


specified in 


called by 


synchronization 


context 


register usage 


input 


exit 


Initiates activity on a device that can support multiple, concurrent |/O 
operations and synchronizes access to its UCB. 


Specify the address of the alternate start-I/O routine in the altstart argument 
to the DDTAB macro. This macro places the address into DDT$L— 
ALTSTART. 


Called by routine EXESALTQUEPKT in module SYSQIOREQ. A driver FDT 
routine generally is the caller of EXESALTQUEPKT. 


An alternate start-I/O routine begins execution at fork IPL, holding the 
corresponding fork lock in a VMS multiprocessing environment. It must 
return control to its EXES$ALTQUEPKT in this context. 


Because an alternate start-I/O routine gains control in fork process context, it 
can access only those virtual addresses that are in system (SO) space. 


An alternate start-I/O routine must preserve the contents of all registers 
except RO through R5. 


Location Contents 
R3 Address of IRP 
R5 Address of UCB 


The alternate start-I/O routine completes I/O requests by calling the routine 
COM$POST. This routine places each IRP in the I/O postprocessing queue 
and returns control to the driver. The driver can then fetch another IRP 
from an internal queue. If no IRPs remain, the driver returns control to 
EXE$ALTQUEPKT, which relinquishes fork level synchronization and returns 
to the driver FDT routine that called it. The FDT routine performs any 
postprocessing and transfers control to the routine EXE$QIORETURN. 





DESCRIPTION 


An alternate start-I/O routine initiates requests for activity on a device that 
can process two or more I/O requests simultaneously. Because the method 
by which the alternate start-I/O routine is invoked bypasses the unit's 
pending-I/O queue (UCB$L_IOQFL) and the device busy flag (UCB$V_BSY 
in UCB$L_STS), the routine is activated regardless of whether the device 
unit is busy with another request. 


As a result, the driver that incorporates an alternate start-I/O routine must 
use its own internal I/O queues (in a UCB extension, for instance) and 
maintain synchronization with the unit’s pending-I/O queue. In addition, if 
the routine processes more than one IRP at a time, it must employ separate 
fork blocks for each request. 
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Cancel-1/O Routine 


specified in 


called by 


synchronization 


context 


register usage 


Prevents further device-specific processing of the |/O request currently 
being processed on a device. 


Supply the address of the cancel-I/O routine in the cancel argument of 

the DDTAB macro. The macro places this address into DDT$L_CANCEL. 
Many drivers specify the system routine IOC6CANCELIO as their cancel-I/O 
routine. 


VMS routines call a driver’s cancel-I/O routine under the following 
circumstances: 


e When a process issues a Cancel-I1/O-on-Channel system service 
(S$CANCEL) 


e When a process deallocates a device, causing the device’s reference count 
(UCB$W_REFC) to become zero (that is, no process I/O channels are 
assigned to the device) 


e When a process deassigns a channel from a device, using the $|DASSGN 
system service 


e¢ When the command interpreter performs cleanup operations as part of 
image termination by canceling all pending I/O requests for the image 
and closing all image-related files open on process I/O channels 


A cancel-I/O routine begins execution at fork IPL, holding the corresponding 
fork lock in a VMS multiprocessing environment. It must return control to its 
caller in this context. 


A cancel-I/O routine executes in kernel mode in process context. 


A cancel-I/O routine must preserve the contents of all registers except RO 
through R5. 
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input 
Location Contents 
R2 Channel index number 
R3 Address of IRP 
R4 Address of PCB of the process for which the |/O 
request is being canceled 
R5 Address of UCB 
R8 Reason for cancellation, one of the following: 
Code Meaning 
CAN$C_CANCEL Called by $CANCEL 
system service 
CAN$C_DASSGN Called by $DASSGN or 
$DALLOC system service 
exit The cancel-I/O routine issues an RSB instruction to return to its caller. 
DESCRIPTION _ A driver’s cancel-I/O routine must perform the following tasks: 


1 


2 


Confirm that the device is busy by examining the device-busy bit in the 
UCB status longword (UCB$V_BSY in UCB$L_STS). 


Confirm that the PID of the request the device is servicing (IRP$L_—PID) 
matches that of the process requesting the cancellation (PCB$L—PID). 


Confirm that the channel-index number of the request the device is 
servicing (IRPS4W_CHAN) matches that specified in the cancel-I/O 
request. 


Cause to be completed (canceled) as quickly as possible all active 1/O 
requests on the specified channel that were made by the process that has 
requested the cancellation. The cancel-I/O routine usually accomplishes 
this by setting UCB$V_CANCEL in the UCB$L_STS. When the next 
interrupt or timeout occurs for the device, the driver’s start-I/O routine 
detects the presence of an active but canceled I/O request by testing this 
bit and takes appropriate action, such as completing the request without 
initiating any further device activity. Other driver routines, such as the 
timeout handling routine, check the cancel-I/O bit to determine whether 
to retry the I/O operation or abort it. 


Device Driver Entry Points 
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Cloned UCB Routine 


specified in 


called by 


synchronization 


context 
register usage 


input 


Performs device-specific initialization and verification of a cloned UCB. 


Specify the address of a cloned UCB routine in the cloneducb argument 

of the DDTAB macro. The macro places this address into DDT$L— 
CLONEDUCB. Only drivers for template devices, such as mailboxes, specify 
a cloned UCB routine. 


EXE$ASSIGN calls the driver’s cloned UCB routine when an Assign I/O 
Channel system service request (SASSIGN) specifies a template device (that 
is, bit UCB$6V_TEMPLATE in UCB$L_STS is set). 


A cloned UCB routine executes at IPL$_ASTDEL, holding the I/O database 
mutex (IOC$GL_—MUTEX). 


A cloned UCB routine executes in kernel mode in process context. 


A cloned UCB routine must preserve the contents of R2. 


Location 

RO 

R2 

R3 

R4 

R5 

UCB$L_FOFL(R2) 
UCB$L_FOBL(R2) 
UCB$L_FPC(R2) 
UCB$L_FR3(R2) 
UCB$L_FR4(R2) 
UCBSW_BUFQUO(R2) 
UCB$L_ORB(R2) 
UCB$L__LINK(R2) 
UCB$L_IOOFL(R2) 
UCB$L_IOOBL(R2) 
UCBSW_UNIT(R2) 
UCB$W_CHARGE(R2) 
UCB$W_REFC(R2) 


Contents 

SS$_NORMAL 

Address of cloned UCB 

Address of DDT 

Address of current PCB 

Address of template UCB 
Address of UCB$L_FOFL(R2) 
Address of UCB$L_FQOFL(R2) 

0 

6) 

O 

0 

Address of cloned ORB 

Address of next UCB in DDB chain 
Address of UCB$L_IOOFL(R2) 
Address of UCB$L_IOQFL(R2) 
Device unit number 

Mailbox byte quota charge (UCB$W_SIZE) 
O 
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UCB$L_STS(R2) 
UCB$W_DEVSTS(R2) 


UCB$L_OPCNT (R2) 
UCB$L_SVAPTE(R2) 
UCB$W_BOFF(R2) 
UCB$W_BCNT(R2) 
UCB$L__ORB(R2) 


ORB$L_OWNER 
of template ORB 


ORB$L_ACL__MUTEX 
of template ORB 
ORB$B_FLAGS 
of template ORB 


ORB$W_PROT 
of template ORB 


ORB$L_ACL _COUNT 
of template ORB 


ORB$L_ACL _DESC 
of template ORB 


ORB$R_MIN_CLASS 
of template ORB 


UCB$V_DELETEUCB set, UCB$V_ONLINE set 


UCB$V_DELMBX set if DEV$V_MBx is set in 
UCB$L_DEVCHAR(R2) 


0 
0 
O 
0 
Address of cloned ORB 
UIC of current process 


FFFF 16 
ORB$V_PROT_16 set 
0 
0 
0 


O in first longword 


exit A cloned UCB routine issues an RSB instruction to return control to 
EXE$ASSIGN. If the routine returns error status in RO, EXES$ASSIGN undoes 
the process of UCB cloning and completes with failure status in RO. 





DESCRIPTION 


When a process requests that a channel be assigned to a template device, 


EXE$ASSIGN does not assign the channel to the template device itself. 
Rather, it creates a copy of the template device’s UCB and ORB, initializing 
and clearing certain fields as appropriate. 


The driver’s cloned UCB routine verifies the contents of these fields and 


completes their initialization. 
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Controller Initialization Routine 


specified in 


called by 


synchronization 


context 


register usage 


input 


exit 


Prepares a controller for operation. 


Use the DPT_STORE macro to place the address of the controller initialization 
routine into CRB$L_INTD+VEC$L _INITIAL. 


SYSGEN calls a driver’s controller initialization routine when processing a 
CONNECT command. Also, VMS calls this routine if the device, controller, 
processor, or adapter to which the device is connected experiences a power 
failure. 


VMS calls a controller initialization routine at IPL$5_POWER. If it must lower 
IPL, the controller initialization routine cannot explicitly do so. Rather, it 
must fork. Because SYSGEN calls the unit initialization routine immediately 
after the controller initialization returns control to it, the driver’s initialization 
routines must synchronize their activities. If the controller initialization 
routine forks, the unit initialization routine must be prepared to execute 
before the controller initialization routine completes. _ 


The portion of the controller initialization that services power failure cannot 
acquire any spin locks. As a result, the routine cannot fork to perform power 
failure servicing. 


Because a controller initialization routine executes within system context, it 
can refer only to those virtual addresses that reside in system (SO) space. 


A controller initialization routine must preserve the contents of all registers 
except RO, R1, and R2. 


Location Contents 

R4 Address of device’s CSR 

R5 Address of IDB associated with the controller 
R6 Address of DDB associated with the controller 
R8 Address of controller's CRB 


The controller initialization routine returns control to its caller with an RSB 
instruction. 
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DESCRIPTION Some controllers require initialization when the system’s driver-loading 
routine loads the driver and when the system is recovering from a power 
failure. Depending on the device, a controller initialization routine performs 
any and all of the following actions: 


¢ Determine whether it is being called as a result of a power failure by 
examining the power bit (UCB$V_POWER in UCB$L_STS) in the UCB. 
A controller initialization routine may want to perform or avoid specific 
tasks when servicing a power failure. 


¢ Clear error-status bits in device registers. 
e Enable controller interrupts. 
e Allocate resources that must be permanently allocated to the controller. 


¢ If the controller is dedicated to a single-unit device, such as a printer, 
fill in IDB$L_ OWNER and set the online bit (UCB$V_ONLINE in 
UCB$L_STS). 


e For generic VAXBI devices, initialize BIIC and device hardware. 
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Driver Unloading Routine 


specified in 


called by 
synchronization 


context 


register usage 


A driver specifies a driver unloading routine if there is any device-specific 
work to do when the driver is unloaded and reloaded. 


Specify the address of the driver unloading routine in the unload argument 
of the DPTAB macro. The driver-loading procedure puts the relative address 
of this routine in DPT$W_UNLOAD. 


SYSGEN calls the driver unloading routine, if it exists, when executing a 
RELOAD command. — 


SYSGEN calls a driver unloading routine at IPL$_POWER. The driver 
unloading routine cannot lower IPL. — 


The driver unloading routine executes in process context. 


The driver unloading routine can use all registers. 





input 
Location Contents 
R6 Address of DDB 
R10 Address of DPT 
exit The driver unloading routine returns exits with an RSB instruction. If it 
returns a success code (bit 0 set) in RO, SYSGEN proceeds to load the new 
version of the driver. If it returns a failure code (bit 0 clear), SYSGEN neither 
unloads the old version of the driver nor loads the new version. 
DESCRIPTION __ Because the driver unloading routine cannot lower IPL from IPL$_POWER 


or obtain spin locks, it is of limited usefulness. It cannot safely modify I/O 
database fields, but can use COM$DRVDEALMEM to return system buffers 
allocated by the driver to nonpaged pool. 
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FDT Routines 


Perform any device-dependent activities needed to prepare the |/O 
database to process an I/O request. 


specified in Use the FUNCTAB macro to specify the set of FDT routines that preprocess 
requests for I/O activity of a given type. Specify the names of the routines in 
the order in which you want them to execute for each type of I/O operation. 


called by The $QIO system service calls a driver's FDT (owns teonntie module 
SYSQIOREQ. 


synchronization — FDT routines are called at IPL$_ASTDEL and must exit at IPL$_ASTDEL. 
FDT routines must not lower IPL below IPL$_ASTDEL. If they raise IPL, 
they must lower it to IPL$_ASTDEL before passing control to any other code. 
Similarly, before exiting they must release any spin locks they may acquire in 
a VMS multiprocessing environment. 


context FDT routines execute in the context of the process that requested the I/O 
activity. If an FDT routine alters the stack, it must restore the stack before 
returning control to the caller of the routine. 


register usage ae routines must preserve the contents of R3 through R8, the AP, and the 
P, 
input 
Location . Contents 
RO Address of FDT routine being called 
R3 Address of IRP 
R4 Address of PCB of the requesting process 
R5 Address of UCB of the device on which 1/O 
activity is requested 
R6 Address of CCB that describes the user-specified 


process-l/O channel 


R7 Number of the bit that specifies the code for the 
requested |/O function 


R8 Address of entry in the function decision table 
that dispatched control to this FDT routine 


AP Address of first function-dependent argument 
(p1) specified in the $010 request 
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exit In a set of FDT routines associated with an I/O function, each, except the 
last, must return control to its caller by means of an RSB instruction. The last 
must exit using one of the following mechanisms: 


Exit Mechanism Function 

JMP EXE$ABORTIO Aborts an I/O request and returns status to the 
caller of the $QIO system service in RO. 

JSB EXESALTQUEPKT Queues an IRP to the driver's alternate start-I/O 
routine without checking the status of the device. 

JMP EXE$FINISHIO Completes the processing of an I/O request, 


returning status to the caller of the $010 
system service. (EXESFINISHIO takes the status 
information from RO and R11 and returns it in the 
|OSB specified in the call to $Q10.) 


JMP EXESFINISHIOC Completes the |/O processing of an I/O request, 
returning status to the caller of the $010 system 
service. (EXE$FINISHIOC takes the status 
information from RO and returns it in the |OSB 
specified in the call to $QlO, clearing the second 
longword of the !OSB.) 


JMP EXESOQIODRVPKT Inserts an IRP into a device’s pending-I/O queue 
if the device is busy, or starts 1/O activity if the 
device is idle. 





DESCRIPTION __ FDT routines validate the function-dependent arguments to a $QIO system 
service request and prepare the I/O database to service the request. For 
each function that a device supports, a set of FDT routines must provide 
preprocessing of requests for that function. For a function that does not 
involve an I/O transfer, a set of FDT routines may complete its processing. 
Otherwise FDT routines can abort the request, pass it to the next FDT routine 
in the set, or pass it to a VMS routine that delivers it to the driver. 
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Interrupt Service Routine 


specified in 


called by 


synchronization 


context 


register usage 
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Processes interrupts generated by a device. 


UNIBUS, Q22-bus, and generic VAXBI devices require an interrupt service 
routine for each interrupt vector the device has. Use the DPT_STORE 
macro to place the address of the interrupt service routine into CRB$L_ 
INTD+VEC$L _ISR. 


If the device has two interrupt vectors, use the DPT_STORE macro to 
place the address of the second interrupt service routine into CRB$L_— 
INTD2+VEC$L _ISR. 


Tape devices on the MASSBUS require an interrupt service routine that 
interrogates the tape formatter (the controller) to determine which drive needs 
attention and whether the interrupt is unsolicited. 


Disk devices on the MASSBUS use the interrupt service routine provided by 
VMS and do not need to provide their own interrupt service routine. 


The interrupt service routine is called either by the VMS interrupt dispatcher 
(for direct-vectored adapters) or by an adapter interrupt service routine (for 
non-direct-vector adapters). 


A driver's interrupt service routine is called, executes, and returns at device 
IPL. In a VMS multiprocessing environment, the interrupt service routine 
must obtain the device lock associated with its device IPL. It performs this 
acquisition as soon as it obtains the address of the UCB of the interrupting 
device. It must release this device lock before dismissing the interrupt. 


At the execution of a driver’s interrupt service routine, the processor is 
running in kernel mode on the interrupt stack. As a result, an interrupt 
service routine can reference only those virtual addresses that reside in 
system (SQ) space. 


If an interrupt service routine uses R6 through R11, the AP, or the FP, it must 
first save the contents of those registers, restoring their contents before exiting 
by means of the REI instruction. MASSBUS drivers must also preserve the 
contents of RO and R1. 
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input 
Location Contents 
OO(SP) Address of longword that contains the address 
of the IDB 
O4(SP) to 24(SP) For UNIBUS, Q22-bus, and generic VAXBI 
devices, the contents of RO through R5 at the 
time of the interrupt 
28(SP) For UNIBUS, Q22-bus, and generic VAXBI 
devices, PC at the time of the interrupt 
32(SP) For UNIBUS, Q22-bus, and generic VAXBI 
devices, PSL at the time of the interrupt 
O4(SP) to 16(SP) for MASSBUS devices, the contents of R2 
through R5 at the time of the interrupt 
20(SP) For MASSBUS devices, PC at the time of the 
interrupt 
24(SP) For MASSBUS devices, PSL at the time of the 
interrupt 
exit Before an interrupt service routine transfers control to the suspended driver, 
it must restore the contents of R3 and R4 from the UCB. It then transfers 
control to the address saved in UCB$L_FPC. 
When it regains control (after the suspended driver forks), an interrupt service 
routine removes the address of the pointer to the IDB from the top of the 
stack and restores the registers VMS saved when dispatching the interrupt 
(RO through R5 for UNIBUS, Q22-bus, and generic VAXBI interrupt service 
routines, R2 through R5 for MASSBUS interrupt service routines). Finally, an 
interrupt service routine dismisses the interrupt with an REI instruction. 
DESCRIPTION An interrupt service routine performs the following functions: 


1 Determines whether the interrupt is expected 
2 Processes or dismisses unexpected interrupts 


3 Activates the suspended driver so it can process expected interrupts 


For MASSBUS devices, a VMS interrupt service routine performs these 
functions. 
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Register Dumping Routine 


specified in 


called by 


synchronization 


context 


register usage 


Copies the contents of a device's registers to an error message buffer or a 
diagnostic buffer. 





Specify the name of the register dumping routine in the regdmp argument 
of the DDTAB macro. This macro places the address of the routine into 
DDT$L_REGDUMP. 


The VMS error logging routines (ERL$DEVICERR, ERL$DEVICTMO, and 
ERL$DEVICEATTN) and diagnostic buffer filling routine (IOC$DIAGBUFILL) 
call the register dumping routine. 


VMS calls a register dumping routine at the same IPL at which the 
driver called the VMS routine ERL${DEVICERR, ERL$DEVICTMO, 
ERL$DEVICEATTIN, or IOC$DIAGBUFILL. A register dumping routine 
must not change IPL. 


A register dumping routine executes within the context of an interrupt service 
routine or a driver fork process, using the kernel-mode stack. As a result, it 
can only refer to those virtual addresses that reside in system (SQ) space. 


The register dumping routine preserves the contents of all registers except RO 
through R2. If it uses the stack, the register dumping routine must restore the 
stack before passing control to another routine, waiting for an interrupt, or 
returning control to its caller. 





input 
Location Contents 
RO Address of buffer into which a register dumping 
routine copies the contents of device registers 
R4 Address of device's CSR (if the driver invoked 
the WFIKPCH macro to wait for an interrupt or 
timeout) 
R5 Address of UCB 
exit The register dumping routine issues an RSB instruction to return to its caller. 
DESCRIPTION _ A register dumping routine fills the indicated buffer as follows: 
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1. Writes a longword value representing the number of device registers to be 
written into the buffer 


2 Moves device register longword values into the buffer following the 
register count longword 
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Start-1/O Routine 


specified in 


called by 


synchronization 


context 


register usage 


input 


Activates a device to process a requested I/O function. 


Specify the name of the start-I/O routine in the start argument of the DDTAB 
macro. This macro places the address of the routine into DDT$L_START. 


The start-I/O routine is called by IOC$INITIATE and IOC$6REQCOM in 
module IOSUBNPAG. 


A start-I/O routine is placed into execution at fork IPL, holding the associated 
fork lock in a VMS multiprocessing environment. It must relinquish control 
of the processor in the same context. 


For many devices, the start-I/O routine raises IPL to IPL$_.POWER to check 
that a power failure has not occurred on the device prior to loading the 
device’s registers. The start-I/O routine initiates device activity at device 
IPL, after acquiring the corresponding device lock in a VMS multiprocessing 
environment. An invocation of the WFIKPCH or WFIRLCH macro to wait for 
a device interrupt releases this device lock. 


Because a start-I/O routine gains control of the processor in the context of a 
fork process, it can refer only to those addresses that reside in system (50) 
space. 


A start-I/O routine must preserve the contents of all registers except RO, R1, 
R2, and R4. If the start-I/O routine uses the stack, it must restore the stack 
before completing the request, waiting for an interrupt, or requesting system 
resources. 


Location Contents 

R3 Address of IRP 

R5 Address of UCB 

UCBSW_BCNT Number of bytes to be transferred, copied from 
the low-order word of IRP$L_BCNT 

UCB$W-_BOFF Byte offset into first page of direct-I/O transfer; 


for buffered-I/O transfers, number of bytes to be 
charged to the process allocating the buffer. 


UCB$L_SVAPTE For a direct-I/O transfer, virtual address of first 
page-table entry (PTE) of |/O-transfer buffer; for 
buffered-I/O transfer, address of buffer in system 
address space 
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Start-1/O Routine 


exit 


The start-I/O routine suspends itself whenever it must wait for a required 
resource, such as a controller data channel or UNIBUS/Q22 bus map 
registers. To do so, it invokes a VMS macro (such as REQPCHAN or 
REQMPR) that saves its context in the UCB fork block, places the UCB in 
a resource wait queue, and returns control to the caller of the start-I/O 
routine. 


The start-I/O routine also suspends itself when it issues a WFIKPCH or 
WFIRLCH macro to initiate device activity. These macros also store the 
driver’s context in the UCB fork block to be restored when the device 
interrupts or times out. 


The start-I/O routine is again suspended if it forks to complete servicing of 
a device interrupt. The IOFORK macro places driver context in the UCB fork 
block, inserts the fork block into a processor-specific fork queue, and requests 
a software interrupt from the processor at the corresponding fork IPL. After 
issuing the IOFORK macro, the routine issues an RSB instruction, returning 
control to the driver’s interrupt service routine. 


The routine completes the processing of an I/O request by invoking the 
REQCOM macro. In addition to initiating device-independent postprocessing 
of the current request, the REQCOM macro also attempts to start the next 
request waiting for a device unit. If there are no waiting requests, the macro 
returns control to the caller of the start-I/O routine. This is often the VMS 
fork dispatcher. 





DESCRIPTION 
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A driver’s start-I/O routine activates a device and waits for a device interrupt 
or timeout. After a device interrupt, the driver’s interrupt service routine ~ 
returns control to the start-I/O routine at device IPL, holding the associated 
device lock in a VMS multiprocessing environment. 


The start-I/O routine usually forks at this time to perform various device- 
dependent postprocessing tasks, and returns control to the interrupt service 
routine. 
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Timeout Handling Routine 


specified in 


called by 


synchronization 


context 


register usage 


Takes whatever action is necessary when a device has not yet responded 
to a request for device activity and the time allowed for a response has 
expired. 


Specify the address of the timeout handling routine in the excpt argument to 
the WFIKPCH or the WFIRLCH macro. 


The WFIKPCH and WFIRLCH macros use this entry point, but only when 
the name of a timeout handling routine is provided in their excpt argument. 
These macros are used in the driver’s start-I/O routine; thus, strictly speaking, 
the driver itself is the only entity that uses this entry point. 


Routines in the VMS module TIMESCHDL call the timeout handling routine 
at the request of the WFIKPCH and WFIRLCH macros. 


A timeout handling routine is called at device IPL and must return to its caller 
at device IPL. In a VMS multiprocessing environment, the processor holds 
both the fork lock and device lock associated with the device at the time of 
the call. 


After taking whatever device-specific action is necessary at device IPL, a 
timeout handling routine can lower IPL to fork IPL to perform less critical 
activities. Because its caller restores IPL to fork IPL (and releases the device 
lock in a VMS multiprocessing environment), if a timeout handling routine 
does lower IPL, it can do so only by forking or by performing the following 
steps: 


e¢ Issue a DEVICEUNLOCK macro to lower to fork level 
e Perform timeout handling activities possible at the lower IPL 


e Issue a DEVICELOCK macro to again obtain the device lock and raise to 
device IPL 


e Issue an RSB instruction to return to its caller 





Because a timeout handling routine executes in the context of a fork process, 
it can access only those virtual addresses that refer to system (SO) space. 


A timeout handling routine can use RO, R1, and R2 freely, but must preserve 
the contents of all other registers. If a timeout handling routine uses the 
stack, it must restore the stack before completing or canceling the current I/O 
request, waiting for an interrupt, or returning control to its caller. 
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Device Driver Entry Points 
Timeout Handling Routine 





input ’ 
Location Contents 
R3 Contents of R3 when the last invocation of 
WFIKPCH or WFIRLCH took place 
R4 Contents of R4 when the last invocation of 
WFIKPCH or WFIRLCH took place 
RS Address of UCB of the device 
UCB$L_STS UCB$V_INT and UCB$V_TIM clear; UCB$V_ 
TIMOUT set 
exit The timeout handling routine issues an RSB instruction to return to its caller. 
DESCRIPTION There are no outputs required from a timeout handling routine, but, 
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depending on the characteristics of the device, the timeout handling routine 
might cancel or retry the current I/O request, send a message to the operator, 
or take some other action. 


Before calling a timeout handling routine, VMS places the device in a state 
in which no interrupt is expected (by clearing the bit UCB$V_INT in field 
UCB$L_STS). If the requested interrupt occurs after this routine is called, it 
will appear to be an unsolicited interrupt. Many drivers handle this situation 
by disabling interrupts while the timeout handling routine executes. 


Device Driver Entry Points 
Unit Delivery Routine 





Unit Delivery Routine 


specified in 


called by 


synchronization 


context 


register usage 


input 


For controllers that can control a variable number of device units, 
determines which specific devices are present and available for inclusion in 
the system's configuration. 


Specify the name of the unit delivery routine in the deliver argument to 
the DPTAB macro. The macro puts the relative address of this routine in 
DPT$W_DELIVER. 


SYSGEN’s AUTOCONFIGURE command calls the unit delivery routine once 
for each unit the controller is capable of controlling. This value is specified in 
the defunits argument to the DPTAB macro. 


The unit delivery routine is called at IPL$_POWER. It must not lower IPL. 


The unit delivery routine executes in the context of the process within which 
SYSGEN executes. 


The unit delivery routine can use RO, R1, and R2 freely, but must preserve 
the contents of all other registers. 


Location Contents 

R3 Address of IDB; O if none exists 

R4 Address of device’s CSR 

R5 Number of unit that the unit delivery routine must 
decide to configure or not to configure 

R6 Address of start of the UNIBUS adapter’s or 


Q22-bus’s I/O space (UNIBUS/Q22-bus devices); 
address of MBA configuration register (MASSBUS 


devices) 

R7 Address of AUTOCONFIGURE command's 
configuration control block (ACF) 

R8 Address of ADP 
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Device Driver Entry Points 
Unit Delivery Routine 


exit A unit delivery routine issues an RSB instruction to return control to the 
SYSGEN autoconfiguration facility. If the routine returns error status in RO, 
SYSGEN does not configure the unit. 


Note that, because generic VAXBI devices are not recognized by SYSGEN’s 
autoconfiguration facility, their drivers do not contain a unit delivery routine. 





DESCRIPTION _ The unit delivery routine determines which units on a controller should be 
configured. For instance, a unit delivery routine can prevent the creation of 
UCBs for devices that do not respond to a test for their presence. 
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Device Driver Entry Points 
Unit Initialization Routine 


Unit Initialization Routine 


specified in 


called by 


synchronization 


context 
register usage 


input 


exit 


Prepares a device for operation and, in the case of a device on a dedicated 
controller, initializes the controller. 


You can specify a unit initialization routine in two ways, either of which will 
suffice for all but a few specific devices. 


¢ Specify the address of the unit initialization routine unitinit argument 
of the DDTAB macro. This macro places the address of the routine into 
DDT$L_UNITINIT. MASSBUS device drivers must use this method. 


e Use the DPT_STORE macro to place the address of the unit initialization 
routine into CRB$L_INTD+VEC$L_UNITINIT. 


SYSGEN calls a driver’s unit initialization routine when processing a 
CONNECT command. VMS calls a unit initialization routine when the 
device, the controller, the processor, or the adapter to which the device is 
connected undergoes power failure recovery. 


VMS calls a unit initialization routine at IPL$6_POWER. If it must lower IPL, 
the controller initialization routine cannot explicitly do so. Rather, it must 
fork. Because SYSGEN calls the unit initialization routine immediately after 
the controller initialization returns control to it, the driver’s initialization 
routines must synchronize their activities. If the controller initialization 
routine forks, the unit initialization routine must be prepared to execute 
before the controller initialization routine completes. 


The portion of the unit initialization that services power failure cannot acquire 
any spin locks. As a result, the routine cannot fork to perform power failure 
servicing. 


Because VMS calls it in system context, a unit initialization routine can only 
refer to those virtual addresses that reside in system (SO) space. 


A unit initialization routine must preserve the contents of all registers except 
RO, R1, and R2. 


Location Contents 

R3 Address of primary CSR. 

R4 Address of secondary CSR, if it exists. (If it does 
not, the contents of R4 are the same as those of 
R3.) 

R5 Address of UCB. 


The unit initialization routine returns control to its caller with an RSB 
instruction. 
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Device Driver Entry Points 
Unit Initialization Routine | 





DESCRIPTION Depending on the device, a unit initialization routine performs any or all of 
the following tasks: 


1 


ao fh W N 


oO 
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Determines whether it is being called as a result of a power failure by 
examining the power bit (UCB$V_POWER in UCB$L_STS) in the UCB. 
A unit initialization routine may want to perform or avoid specific tasks 
when servicing a power failure. 


Clears error-status bits in device registers. 
Enables controller interrupts. 
Sets the online bit (UCB$V_ONLINE in UCB$L_STS). 


Allocates resources that must be permanently allocated to the device or, 
for some devices, the controller. 


If the device has a dedicated controller, as some printers do, fills in 
IDB$L_OWNER. 


For dedicated VAXBI controllers, initializes BIIC and device hardware. 


Device Driver Entry Points 
Unsolicited Interrupt Service Routine 


Unsolicited Interrupt Service Routine 


specified in 


called by 


synchronization 


context 


register usage 


Services an interrupt from a MASSBUS disk that is not the result of a 
driver's request. 


Specify the name of the unsolicited interrupt service routine in the unsolic 
argument to the DDTAB macro. This macro places the address of the routine 
into DDT$L_UNSOLINT. 


The MASSBUS adapter’s interrupt service routine (MBA$INT in module 
ADPERRSUB of the SYSLOA facility) calls a driver’s unsolicited interrupt 
service routine. 


An unsolicited interrupt service routine is called, executes, and returns at 
device IPL. 


Because the unsolicited interrupt service routine executes in kernel mode on 
the interrupt stack, it can only refer to those addresses that reside in system 
(SO) space. 


The unsolicited interrupt service routine must not alter the contents of 
registers R6 through R11, the AP, or the FP. 





input 
Location Contents 
R4 Address of MBA's configuration register 
Rb5 Address of UCB 
exit An unsolicited interrupt service routine issues an RSB instruction to return 
control to the MASSBUS adapter’s interrupt service routine. 
DESCRIPTION Only drivers of MASSBUS disks must provide unsolicited interrupt service 


routines. All other devices detect unsolicited interrupts in their interrupt 
service routines. 


The routine that handles these unsolicited interrupts must determine the 
nature of the interrupt and act accordingly, depending on the characteristics 
of the device and controller. Examples of such unsolicited interrupts include 
disks being placed on line or taken off line. 
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Sample Driver for the RL11, RLO1, and RLO2 


This example driver, DLDRIVER, drives a disk device on both the UNIBUS 


and the Q22 bus. 


.TITLE DLDRIVER - VAX/VMS RL11/RLO1,RLO2 DISK DRIVER 
.IDENT 'X-7' 


5 OR A ge i 2 a A 2 OO AS OK 8 eR OK IE 2g AE ES 2 AE 2 2 RE gE OR 2g RO gg Og 2 OK 2 gO OB RO OK OE EK OK KOK 


** * *¥ ¥ Kee HK Ke He Re KR HEH Ke He He Ke KH K 


COPYRIGHT (c) 1978, 1980, 1982, 1984 BY 
DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASSACHUSETTS. 
ALL RIGHTS RESERVED. 


THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED 
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE 
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER 
COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY 
OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY 
TRANSFERRED . 


THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE 
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL’ EQUIPMENT 
CORPORATION. 


DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS 
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL. 


EOE 8 RE KR KR FH HH RH HK He KOR He RO 


OOO CC CA ASR GR i a a ik 42k 40k 
; FACILITY: 
; VAX/VMS RL1i1/RLO1,RLO2 DISK DRIVER 


°K AK 


. PAGE 

; ABSTRACT: 

; THIS MODULE CONTAINS THE TABLES AND ROUTINES NECESSARY TO 
; PERFORM ALL DEVICE-DEPENDENT PROCESSING OF AN I/O REQUEST 
; FOR RL11/RLO1,RLO2 DISK TYPES ON A VAX/VMS SYSTEM. 

: THE DISKS HAVE THE FOLLOWING PHYSICAL GEOMETRY: 

; , TRACKS/ SECTORS/ BYTES/ MAXIMUM 
; # CYL CYLINDER TRACK SECTOR BLOCKS 
; RLOL 256 2 40 256 10240 

; RLO2 512 2 40 256 20480 


' SINCE THE SECTOR SIZE IS ONLY 1/2 BLOCK, LOGICAL TO PHYSICAL 
: CONVERSION OF THE DISK ADDRESS IS DONE IN THE DRIVER STARTIO 
; ROUTINE RATHER THAN IN THE IOC$CVTLOGPHY FDT ROUTINE. 


; OVERLAPPED SEEKS ARE NOT ATTEMPTED BECAUSE THE DEVICE DOES 


Sample Driver for the RL11, RLO1, and RLO2 


, 


NOT INTERRUPT AT THE COMPLETION OF A SEEK. 


ALSO, THE DEVICE DOES NOT PERFORM AN IMPLICIT SEEK WHEN PERFORMING 


A READ OR WRITE FUNCTION,SO SEEK FUNCTIONS ARE ISSUED BY THIS 
DRIVER WHERE NECESSARY PRIOR TO ISSUING A READ OR WRITE FUNCTION. 
THE READ OR WRITE FUNCTION IS THEN ISSUED AS SOON AS THE RL1i 
CONTROLLER BECOMES READY (WHILE THE SEEK IS IN PROGRESS), AND A 
WAIT FOR INTERRUPT (UPON COMPLETION OF THE READ OR WRITE) IS 
ISSUED. IF A SEEK FUNCTION IS REQUESTED SEPARATELY FROM A READ OR 
WRITE, A DUMMY READ HEADER FUNCTION IS ISSUED FOLLOWING THE SEEK 
FUNCTION AND A WAIT FOR INTERRUPT (UPON COMPLETION OF THE READ 
HEADER) IS ISSUED. 


THE IO$X_INHSEEK FUNCTION MODIFIER IS TREATED AS A NO-OP BY 


THIS DRIVER, SINCE AN EXPLICIT SEEK IS NECESSARY FOR THE RLO2 
TO TRANSFER DATA PROPERLY. 


THE RL'S DO NOT READ OR WRITE BEYOND THE END OF TRACK (THEY DO NOT 
AUTOMATICALLY SEEK THE NEXT TRACK), SOQ ALL READ AND WRITE FUNCTIONS 
ARE BROKEN UP BY THIS DRIVER INTO PARTIAL TRANSFERS TO THE END OF 
TRACK, FOLLOWED BY A SEEK TO THE NEXT TRACK, THEN ANOTHER READ OR 
WRITE FUNCTION UNTIL THE TOTAL DATA TRANSFER IS COMPLETE. 


. PAGE 
.SBITL EXTERNAL AND LOCAL DEFINITIONS 


; EXTERNAL SYMBOLS 


; LOCAL 


$ADPDEF ;DEFINE ADAPTER CONTROL BLOCK 
$CRBDEF ;DEFINE CHANNEL REQUEST BLOCK 
$DCDEF ;DEFINE DEVICE CLASS 

$DDBDEF ; DEFINE DEVICE DATA BLOCK 
$DEVDEF ;DEFINE DEVICE CHARACTERISTICS 
$DPTDEF ;DEFINE DRIVER PROLOGUE TABLE © 
$DYNDEF ;DEFINE DYNAMIC DATA STRUCTURE TYPES 
$EMBDEF ;DEFINE ERROR MESSAGE BUFFER 
$IDBDEF ;DEFINE INTERRUPT DATA BLOCK 
$IODEF ;DEFINE I/0 FUNCTION CODES 
$IRPDEF ;DEFINE I/O REQUEST PACKET 
$PRDEF ;DEFINE PROCESSOR REGISTERS 
$PTEDEF ;DEFINE SYSTEM PTES 

$SSDEF ;DEFINE SYSTEM STATUS CODES 
$UCBDEF ;DEFINE UNIT CONTROL BLOCK 
$VADEF ;DEFINE VIRTUAL ADDRESS BITS 
$VECDEF ;DEFINE INTERRUPT VECTOR BLOCK 
MACROS . 

EXFUNCL 


BRANCH TO SUBROUTINE WHICH REQUESTS CHANNEL (IF NOT ALREADY OWNED), 
EXECUTES FCODE (OR R3) FUNCTION, AND BRANCHES TO BDST ON ERROR 


-MACRO EXFUNCL BDST,FCODE 


.IF NB FCODE ;IS FCODE NONBLANK? 

MOVZBL #CD'FCODE,R3 ; IF NB - SPECIFY FCODE FUNCTION 

. ENDC ;IF B - SPECIFY FNIN IN EXISTING R3 
BSBW FEXL ; EXECUTE FUNCTION 

.BYTE BDST-.-1 ;WHERE TO GO IF ERROR 


. ENDM 


; GENF 


Sample Driver for the RL11, RLO1, and RLO2 


GENERATE FUNCTION TABLE ENTRY AND CASE TABLE INDEX SYMBOL 


. MACRO 


.ENDM 


; CKPWR 
: DISABLE 
; AND PUT 


. MACRO 


Li: 
. ENDM 


; LOCAL SYMBOLS 
RL_NUM_REGS 
RL_SLM 
UCB$B_DL_DCHEK 


+ 


GENF FCODE 
CD'FCODE=.-FTAB/2 
WORD FCODE!RL_CS_M_IE ;FCODE WITH INT ENABLE BIT 


INTERRUPTS, CHECK IF POWER HAS FAILED, 
DEVICE UNIT NUMBER IN R2<9:8> 


CKPWR SAVE_RO=YES, ?7L1 


CLRL R2 ;CLEAR R2 FOR UNIT NUMBER 

INSV UCB$W_UNIT(R5),- ;PUT UNIT # IN R2<9:8> 
#8, #2,R2 fore. 

DEVICELOCK - 
LOCKADDR=UCB$L_DLCK(R5) ,- ; LOCK DEVICE ACCESS 
LOCKIPL=UCB$B_DIPL(R5),- ; RAISE IPL 
SAVIPL=-(SP),- ;SAVE CURRENT IPL 
PRESERVE=' SAVE_RO 

SETIPL #31,- ;DISABLE ALL INTERRUPTS 
ENV IRON=UNIPROCESSOR 

BBC #UCB$V_POWER,- ;IF CLR - NO POWER FAILURE 
UCB$W_STS(R5) ,L1 

; POWERFAILURE! 

DEVICEUNLOCK - 
LOCKADDR=UCB$L_DLCK(R5),- ; UNLOCK DEVICE ACCESS 
NEWIPL=(SP)+,- ;RESTORE IPL 
PRESERVE='SAVE_RO 

BRW RETREG ;EXIT 


;RETURN FOR NO POWER FAILURE 


=4 i ;NUMBER OF DEVICE REGISTERS 
=5 ;STATE=SEEK LINEAR MODE (READY TO GO) 
=UCB$W_OFFSET+1 ;REDEFINE FOR DATA CHECK USE 


; UCB OFFSETS WHICH FOLLOW THE STANDARD UCB FIELDS 


’ 


$DEF INI 


UCB ;START OF UCB DEFINITIONS 
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. =UCB$K_LCL_DISK_LENGTH 


$DEF 
$DEF 
$DEF 
$DEF 
$DEF 
$DEF 
$DEF 
$DEF 
$DEF 
$DEF 
$DEF 
$DEF 
$DEF 
$DEF 
$DEF 
$DEF 
$DEF 
$DEF 
$DEF 


$DEF 
$EQU 


UCB$W_DL_PBCR 
UCB$W_DL_CS 
UCB$W_DL_BA 
UCB$W_DL_DA 
UCB$W_DL_MP 
UCB$W_DL_DPN 
UCB$L_DL_SVAPTE 
UCB$L_DL_DPR 
UCB$L_DL_BUF ADR 
UCB$L_DL_FMPR 
UCB$A_DL_MOVRIN 
UCB$L_DL_PMPR 
UCB$B_DL_DPPE 
UCB$W_DL_DB 
UCB$B_DL_XBA 
UCB$W_DL_SBA 
UCB$A_DL_BUF_VA 
UCB$A_DL_BUF_PA 
UCB$W_DL_FLAGS 
$VIELD UCB,O,<- 


<DL_22BIT, ,M>,- 


. BLKW 
. BLKW 
. BLKW 
. BLKW 
. BLKW 
. BLKW 


. BLKL 


. BLKL 


. BLKL 
. BLKB 
. BLKW 
. BLKB 
. BLKW 
. BLKL 
. BLKL 
. BLKW 


a a a a 


_ 


= 


PPRRERPWrRHE 


<DL_MAPPING, ,M>, - 


> 
UCB$K_DL_LEN 


. BLKW 


UCB$K_DL_BUFSZ 20 


$DEFEND UCB 


1 


; RL11/RLO1 REGISTER OFFSETS FROM 


a] 


$DEF 


$DEF 
$DEF 


$DEFINI RL 


RL_CS 
_VIELD 


. BLKW 
RL_CS,0,<- 


<DRDY, ,M>,- 
<FCODE, 3>, - 


<XBA,2>,- 
<IE, ,M>,- 


<CRDY, ,M>,- 


<DS ,2>,- 


<OPI, ,M>,- 


<CRC, ,M>, 
<DLT, ,M>, 
<NXM, ,M>, 
<DE, ,M>,- 


<CE, ,M>- 


RL_BA 


RL_DA 
_VIELD 


. BLKW 


. BLKW 
RL_DA,O,<- 


<MRK, ,M>, - 
<STS, ,M>, - 


<,1>,- 


<RST, ,M>, - 


<,12>,- 


1 


1 
1 


;BEGIN DEFINITIONS AT END OF UCB 
;PARTIAL BYTE COUNT 

;CONTROL STATUS REGISTER 

;BUS ADDRESS REGISTER 

;DISK ADDRESS REGISTER 
;MULTIPURPOSE REGISTER 

;DATA PATH NUMBER 

;SAVED SVAPTE OF THE USER'S BUFFER 
;DATAPATH REGISTER 

;USER BUFFER ADDRESS 

;FINAL MAP REGISTER 

;BUFFER MOVE ROUTINE ADDRESS 
;PREVIOUS MAP REGISTER 

;DATAPATH PURGE ERROR 

;DATA BUFFER REGISTER 

;BUS ADDRESS EXTENSION BITS 
;SAVED BUFFER ADDRESS 

;PHYSICAL BUFFER VIRTUAL ADDRESS 
;PHYSICAL BUFFER PHYSICAL ADDRESS 
; FLAGS 

;START THE FLAG DEFINITIONS 

;22 BIT ADDRESSING 

; ADAPTER MAPPING 

;END OF FLAG DEFINITIONS 

; LENGTH OF UCB 

;BUFFER SIZE = 40 SECTORS * 

;256 BYTES/SECTOR / 512 BYTES/PAGE 
;END OF UCB DEFINITIONS 


CSR ADDRESS 


; START OF REGISTER DEFINITIONS 


;CONTROL STATUS REGISTER (CSR) 
;START OF CSR BIT DEFINITIONS 
; DRIVE READY 

; FUNCTION CODE 

; BUS ADDRESS EXTENSION BITS 

; INTERRUPT ENABLE 

; CONTROLLER READY 

; DRIVE SELECT 

; OPERATION INCOMPLETE 

; DATA CRC OR HEADER CRC 

; DATA LATE OR HEADER NOT FOUND 
; NONEXISTENT MEMORY 

; DRIVE ERROR 

; COMPOSITE ERROR 

;END CSR BIT DEFINITIONS 


;BUS ADDRESS REGISTER (BAR) 


;DISK ADDRESS REGISTER (DAR) 
;START OF DAR BIT DEFINITIONS 
; MARK (ALWAYS 1) 

; GET STATUS 

; RESERVED BIT 

; RESET 

; RESERVED BITS 

;END OF DAR BIT DEFINITIONS 
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$DEF RL_MP . BLKW 1 

_VIELD RL_MP,O,<- 
<STA,3>,- 
<BH, ,M>,- 
<HO, ,M>,- 
<CO, ,M>,- 
<HS, ,M>,- 
<TYP, ,M>,- 
<DSE, ,M>,- 
<VC, ,M>,- 
<WGE, ,M>,- 
<SPE, ,M>,- 
<SKTO, ,M>,- 
<WL, ,M>,- 
<CHE, ,M>,- 
<WDE, ,M>- 

> 


$DEF RL_BAE ._BLKW i 
$DEFEND RL 


; HARDWARE FUNCTION CODES 


F_NOP=0*2 
F_UNLOAD=F_NOP 
F_SEEK=3*2 
F_RECAL=F _NOP 
F_DRVCLR=2*2 
F_RELEASE=F_NOP 
F_OFFSET=F_NOP 
F_RETCENTER=F _NOP 
F_PACKACK=2*2 
F_SEARCH=F_NOP 
F_WRITECHECK=1*2 
F_WRITEDATA=5*2 
F_WRITEHEAD=F _NOP 
F_READDATA=6*2 
F_READHEAD=4*2 
F_AVAILABLE=F _NOP 
F_GETSTATUS=2+2 


. PAGE 
.SBITL STANDARD TABLES 


; DRIVER PROLOGUE TABLE 


7M 
;S 


ULTIPURPOSE REGISTER (MPR) 
TART OF MPR BIT DEFINITIONS 
DRIVE STATE 


; BRUSH HOME 


’ 


, 


HEADS OUT 

COVER OPEN 

HEAD SELECT 

DRIVE TYPE 

DRIVE SELECT ERROR 
VOLUME CHECK 
WRITE GATE ERROR 
SPIN ERROR 

SEEK TIME OUT 


; WRITE LOCK 
; CURRENT HEAD ERROR 


; WRITE DATA ERROR 


iE 


;E 


:N 
;N 
;s 
3N 
7D. 
;N 
3N 
;N 
;P 
;N 
;W 
;W 
;N 


ND MPR BIT DEFINITIONS 


; BUS ADDRESS EXTENSION REGISTER (BAE) 


ND RL11/RLO1 REGISTER DEFINITIONS 


O OPERATION 

O OPERATION 

EEK CYLINDER 

OQ OPERATION 

RIVE CLEAR (GET STATUS) 
0 OPERATION 

O OPERATION 

0 OPERATION 

ACK ACKNOWLEDGE (SET VOLUME VALID) 
0 OPERATION 

RITE CHECK 

RITE DATA 

0 OPERATION 


;READ DATA 
;READ HEADER 


iN 


0 OPERATION 


;GET STATUS (DRIVER INTERNAL USE) 


; THE DPT DESCRIBES DRIVER PARAMETERS AND I/O DATABASE FIELDS 
; THAT ARE TO BE INITIALIZED DURING DRIVER LOADING AND RELOADING 


DPTAB - 
END=DL_END, - 
ADAPTER=UBA, - 
FLAGS=DPT$M_SVP, - 


UCBSIZE=UCB$K_DL_LEN, - 


NAME=DLDRIVER 


3D 


PT CREATION MACRO 


;END OF DRIVER LABEL 
; ADAPTER TYPE = UNIBUS 


;S 
7L 


YSTEM PAGE-TABLE ENTRY REQUIRED 
ENGTH OF UCB 


;DRIVER NAME 
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; DRIVER DISPATCH 


DPT_STORE INIT ;START CONTROL BLOCK INIT VALUES 
DPT_STORE DDB,DDB$L_ACPD,L,<*A\F11\> ;DEFAULT ACP NAME 
DPT_STORE DDB,DDB$L_ACPD+3,B,DDB$K_CART ;ACP CLASS 

DPT_STORE UCB,UCB$B_FLCK,B,SPL$C_IOLOCK8 ;FORK LOCK INDEX 
DPT_STORE UCB ,UCB$L_DEVCHAR,L, - UPENLCE CHARACTERISTICS 


<DEV$M_FOD- ; FILES ORIENTED 

!DEV$M_DIR- ; DIRECTORY STRUCTURED 

!DEV$M_AVL- ; AVAILABLE 

!DEV$M_ELG- ; ERROR LOGGING 

!DEV$M_SHR- ; SHAREABLE 

!DEV$M_IDV- ; INPUT DEVICE 

!DEV$M_ODV- ; OUTPUT DEVICE 

!DEV$M_RND> ; RANDOM ACCESS 
DPT_STORE UCB,UCB$L_DEVCHAR2,L,-; DEVICE CHARACTERISTICS 

<DEV$M_NNM> PREFIX NAME WITH "node$" 
DPT_STORE UCB,UCB$B_DEVCLASS,B, Des. DISK ;DEVICE CLASS 


DPT_STORE UCB,UCB$W_DEVBUFSIZ,W,512 ;DEFAULT BUFFER SIZE 

DPT_STORE UCB,UCB$B_SECTORS,B,40 ;NUMBER OF SECTORS PER TRACK 

DPT_STORE UCB,UCB$B_TRACKS,B,2 ;NUMBER OF TRACKS PER CYLINDER 

DPT_STORE UCB,UCB$B_DIPL,B, 21 ;DEVICE IPL 

DPT_STORE UCB,UCB$B_ERTMAX,B,8 ;MAX ERROR RETRY COUNT 

DPT_STORE UCB,UCB$W_DEVSTS,W,- ;INHIBIT LOG TO PHYS CONVERSION IN FDT 

<UCB$M_NOCNVRT> So 5 

DPT_STORE REINIT ;START CONTROL BLOCK RE-INIT VALUES 

DPT_STORE CRB,CRB$L_INTD+4,D,DL_INT ;INTERRUPT SERVICE ROUTINE ADDRESS 

DPT_STORE CRB,CRB$L_INTD+VEC$L_INITIAL,- ;CONTROLLER INIT ADDRESS 
D,DL_RL11_INIT ak 

DPT_STORE CRB,CRB$L_INTD+VEC$L_UNITINIT,- ;UNIT INIT ADDRESS 
D,DL_RLOX_INIT eae 

DPT_STORE DDB,DDB$L_DDT,D,DL$DDT ;DDT ADDRESS 

DPT_STORE END ;END OF INITIALIZATION TABLE 


TABLE 


THE DDT LISTS ENTRY POINTS FOR DRIVER SUBROUTINES WHICH ARE 
CALLED BY THE OPERATING SYSTEM. 


DDTAB 


;DDT CREATION MACRO 


DEVNAM=DL, - ;NAME OF DEVICE 
START=DL_STARTIO, - ;START I/O ROUTINE 
UNSOLIC=DL_UNSOLNT, - ; UNSOLICITED INTERRUPT 
FUNCTB=DL_FUNCTABLE, - ; FUNCTION DECISION TABLE 
CANCEL=0, - ;CANCEL=NO-OP FOR FILES DEVICE 
REGDMP=DL_REGDUMP,, - ;REGISTER DUMP ROUTINE 


DIAGBF=<<RL_NUM_REGS+5+5+3+1>*4>,- ;BYTES IN DIAG BUFFER 
ERLGBF=<<<RL_NUM_REGS+5+1>*4>+EMB$L_DV_REGSAV> ;BYTES IN 


;ERROR LOG BUFFER 


; DIAGNOSTIC BUFFER SIZE = <<4 RLO2 REGISTER LONGWORDS + 5 UCB FIELD LONGWORDS 


+ 5 IOC$DIAGBUFILL LONGWORDS + 3 BUFFER ALLOCATION 
LONGWORDS + 1 LONGWORD FOR # REGISTERS IN DL_REGDUMP> 
* 4 BYTES/LONGWORD> 


; ERROR LOG BUFFER SIZE = <<<4 RLO2 REGISTER LONGWORDS + 5 UCB FIELD LONGWORDS 
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+ 1 LONGWORD FOR # REGISTERS IN DL_REGDUMP> 
* 4 BYTES/LONGWORD> + BYTES NEEDED FOR ERROR LOGGER 
TO SAVE SOFTWARE REGISTERS> 
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; HARDWARE FUNCTION CODE TABLE 


: THIS TABLE MERGES THE FUNCTION CODE BITS WITH THE 
: INTERRUPT ENABLE BIT AND GENERATES THE CASE TABLE 
; INDEX SYMBOL. 


FTAB:  GENF F_NOP ; NO-OP 
GENF F_UNLOAD ;UNLOAD VOLUME (NOP) 
GENF F_SEEK ; SEEK 
GENF F_RECAL ;RECALIBRATE (NOP) 
GENF F_DRVCLR ;DRIVE CLEAR (RESET & GET STATUS) 
GENF F_RELEASE ;RELEASE PORT (NOP) 
GENF § F_OFFSET ;OFFSET HEADS (NOP) 
GENF F_RETCENTER ;RETURN HEADS TO CENTERLINE (NOP) 
GENF F_PACKACK ;PACK ACKNOWLEDGE (RESET & GET STATUS) 
GENF F_SEARCH ;SEARCH (NOP) 
GENF F_WRITECHECK ;WRITE CHECK 
GENF F_WRITEDATA. ;WRITE DATA 
GENF F_READDATA ;READ DATA 
GENF F_WRITEHEAD ;WRITE HEADERS (NOP) 
GENF F_READHEAD ;READ HEADERS 
GENF F_NOP ;place holder 
GENF F_NOP ;place holder 
GENF F_AVAILABLE ; AVAILABLE 
. PAGE 


; FUNCTION DECISION TABLE 

: THE FDT LISTS VALID FUNCTION CODES, SPECIFIES WHICH 
i CODES ARE BUFFERED, AND DESIGNATES SUBROUTINES TO 

; PERFORM PREPROCESSING FOR PARTICULAR FUNCTIONS. 


DL_FUNCTABLE: 


FUNCTAB ,- ;LIST LEGAL FUNCTIONS 
<NOP, - ; NO-OP 
UNLOAD, - ; UNLOAD 
SEEK , - ; SEEK 
DRVCLR, - ; DRIVE CLEAR 
PACKACK , - ; PACK ACKNOWLEDGE 
SENSECHAR,, - ; SENSE CHARACTERISTICS 
SETCHAR,, - ; SET CHARACTERISTICS 
SENSEMODE, - ; SENSE MODE 
SETMODE, - ; SET MODE 
WRITECHECK, - ; WRITE CHECK 
READHEAD, - ; READ HEADER 
READLBLK , - ; READ LOGICAL BLOCK 
WRITELBLK , - ; WRITE LOGICAL BLOCK 
READPBLK, - ; READ PHYSICAL BLOCK 
WRITEPBLK , - ; WRITE PHYSICAL BLOCK 
READVBLK, - ; READ VIRTUAL BLOCK 
WRITEVBLK , - ; WRITE VIRTUAL BLOCK 
AVAILABLE, - ; AVAILABLE 
ACCESS, - ; ACCESS FILE / FIND DIRECTORY ENTRY 
ACPCONTROL, - ; ACP CONTROL FUNCTION 
CREATE, - ; CREATE FILE AND/OR DIRECTORY ENTRY 
DEACCESS , - ; DEACCESS FILE 
DELETE, - ; DELETE FILE AND/OR DIRECTORY ENTRY 
MODIFY, - ; MODIFY FILE ATTRIBUTES 
MOUNT- ; MOUNT VOLUME 
> 

FUNCTAB ,- ; BUFFERED FUNCTIONS 
<NOP, - ; NO-OP 
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FUNCTAB 


FUNCTAB 


FUNCTAB 


FUNCTAB 


FUNCTAB 


FUNCTAB 


FUNCTAB 


FUNCTAB 


FUNCTAB 


UNLOAD, - ; UNLOAD 

SEEK , - ; SEEK 

DRVCLR, - : DRIVE CLEAR 

PACKACK, - ; PACK ACKNOWLEDGE 

. SENSECHAR, - ; SENSE CHARACTERISTICS 

SETCHAR, - : SET CHARACTERISTICS 
SENSEMODE, - ; SENSE MODE 

SETMODE, - ; SET MODE 
AVAILABLE, - ; AVAILABLE 

ACCESS, - ; ACCESS FILE / FIND DIRECTORY ENTRY 
ACPCONTROL, - ; ACP CONTROL FUNCTION 
CREATE, - ; CREATE FILE AND/OR DIRECTORY ENTRY 
DEACCESS, - ; DEACCESS FILE 

DELETE, - : DELETE FILE AND/OR DIRECTORY ENTRY 
MODIFY, - ; MODIFY FILE ATTRIBUTES 
MOUNT- ; MOUNT VOLUME 

> 

DL_ALIGN, - :TEST ALIGNMENT FUNCTIONS 
<READHEAD , - ; READ HEADER 

READLBLK, - ; READ LOGICAL BLOCK 
READPBLK, - - READ PHYSICAL BLOCK 
READVBLK, - ; READ VIRTUAL BLOCK 
WRITECHECK, - ; WRITE CHECK 

WRITELBLK , - : WRITE LOGICAL BLOCK 
WRITEPBLK , - ; WRITE PHYSICAL BLOCK 
WRITEVBLK- : WRITE VIRTUAL BLOCK 

> 

+ACP$READBLK , - :READ FUNCTIONS 

<READHEAD , - : READ HEADER 

READLBLK, - ; READ LOGICAL BLOCK 
READPBLK, - - READ PHYSICAL BLOCK 
READVBLK- ; READ VIRTUAL BLOCK 

> 

+ACP$WRITEBLK, - ‘WRITE FUNCTIONS 
<WRITECHECK, - : WRITE CHECK 

WRITELBLK, - ; WRITE LOGICAL BLOCK 
WRITEPBLK , - - WRITE PHYSICAL BLOCK 
WRITEVBLK- ; WRITE VIRTUAL BLOCK 

> 

+ACP$ACCESS, - - : ACCESS FUNCTIONS 

<ACCESS , - - ACCESS FILE / FIND DIRECTORY ENTRY 
CREATE- ; CREATE FILE AND/OR DIRECTORY ENTRY 
> 

+ACP$DEACCESS, - :DEACCESS FUNCTION 
<DEACCESS- - DEACCESS FILE 

> 

+ACP$MODIFY , - ;MODIFY FUNCTIONS 
<ACPCONTROL, - - ACP CONTROL FUNCTION 
DELETE, - ; DELETE FILE AND/OR DIRECTORY ENTRY 
MODIFY- ; MODIFY FILE ATTRIBUTES 

> 

+ACP$MOUNT, - ‘MOUNT FUNCTION 

<MOUNT- ; MOUNT VOLUME 

> 

+EXE$LCLDSKVALID, - ;LOCAL DISK VALID FUNCTIONS 
<UNLOAD , - “UNLOAD VOLUME 

AVAILABLE, - ;UNIT AVAILABLE 

PACKACK- -PACK ACKNOWLEDGE 

> 

+EXE$ZEROPARM, - :ZERO PARAMETER FUNCTIONS 
<NOP, - ; NO-OP 
UNLOAD, - ; UNLOAD 

DRVCLR, - ; DRIVE CLEAR 


++ 
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PACKACK, - ; PACK ACKNOWLEDGE 
AVAILABLE, - ; AVAILABLE 
> 

FUNCTAB +EXE$ONEPARM, - ;ONE PARAMETER FUNCTION 
<SEEK- ; SEEK 
> 

FUNCTAB +EXE$SENSEMODE, - ; SENSE FUNCTIONS 
<SENSECHAR,, - ; SENSE CHARACTERISTICS 
SENSEMODE- ; SENSE MODE 
> 

FUNCTAB +EXE$SETCHAR, - ;SET FUNCTIONS 
<SETCHAR, - ; SET CHARACTERISTICS 
SETMODE- ; SET MODE 
> 

. PAGE 


.SBITL CONTROLLER INITIALIZATION ROUTINE 


; FUNCTIONAL DESCRIPTION: 


THIS ROUTINE IS A NO-OP FOR THE RL11 BUT MUST BE INCLUDED 
SINCE IT IS CALLED WHEN THE RLO2 IS BOOTED AS A SYSTEM DEVICE. 


THE OPERATING SYSTEM CALLS THIS ROUTINE: 
~ AT SYSTEM STARTUP 
- DURING DRIVER LOADING 
DURING RECOVERY FROM POWER FAILURE 


; INPUTS: 


R4 - CSR ADDRESS (DEVICE CONTROL STATUS REGISTER) 
RS - IDB ADDRESS (INTERRUPT DATA BLOCK) 
R6 - DDB ADDRESS (DEVICE DATA BLOCK) 


R8 - CRB ADDRESS (CHANNEL REQUEST BLOCK) 
ALL INTERRUPTS ARE LOCKED OUT 


; OUTPUTS: 


DL_RL11_INIT: 


10$: 


20$ : 


ALL REGISTERS EXCEPT RO-R3 ARE PRESERVED. 
CONTROL IS RETURNED TO THE CALLER. 


;CONTROLLER INITIALIZATION 
; FOR MICROVAX I, ALLOCATE A PHYSICALLY CONTIGUOUS BUFFER 
; AREA FOR PERFORMING I/0.. 


ADPDISP SELECT=ADAP_MAPPING,- ; Allocate a physically contiguous 
ADDRLIST=<<YES ,20$>>,- ; buffer for those adapters that 
CRBADDR=R8, - ; don't support mapping. 


SCRATCH=RO 


MOVZWL #UCB$K_DL_BUFSZ,R1 
JSB G"EXE$ALOPHYCNTG ; ALLOCATE PHYSICALLY CONTIGUOUS MEMORY 
BLBC RO, 20$ ;EXIT ON ERROR 

MOVL R2,CRB$L_AUXSTRUC (R8) ;GET BUFFER VIRTUAL ADDRESS 


;LOAD SIZE OF BUFFER 


RSB ;RETURN TO CALLER 

CLRL CRB$L_AUXSTRUC (R8) ; INDICATE MEMORY ALLOCATION FAILURE 
RSB ;RETURN TO CALLER 

. PAGE 


-SBITL UNIT INITIALIZATION ROUTINE 


E-9 


Sample Driver for the RL11, RLO1, and RLO2 


+4 


; DL_RLOX_INIT - UNIT INITIALIZATION ROUTINE 

; FUNCTIONAL DESCRIPTION: 

; THIS ROUTINE READIES THE RLO1/RLO2 UNITS FOR I/O OPERATIONS. 
; THE OPERATING SYSTEM CALLS THIS ROUTINE: 

; - AT SYSTEM STARTUP 

; ~ DURING DRIVER LOADING 

, ~ DURING RECOVERY FROM POWER FAILURE 


; INPUTS: 

; R4 ~ CSR ADDRESS (CONTROLLER STATUS REGISTER) 
; RS - UCB ADDRESS (UNIT CONTROL BLOCK) 

; OUTPUTS: 


; THE DRIVE UNIT IS RESET, UCB FIELDS ARE INITIALIZED, AND THE 
i ROUTINE WAITS FOR ONLINE UNITS TO SPIN UP. ALL REGISTERS 
; EXCEPT RO-R3 ARE PRESERVED. 


DL_RLOX_INIT: ;RLO1/RLO2 UNIT INITIALIZATION 
MOVW #1@UCB$V_DL_MAPPING, - ; DEFAULT TO ADAPTER MAPPING 
UCB$W_DL_FLAGS (R5) ; AND 18 BIT ADDRESSING 


ADPDISP SELECT=ADAP_MAPPING, - 
ADDRLIST=<<YES , 2$>>, - 
UCBADDR=R5, - 
SCRATCH=RO 
CLRW UCB$W_DL_FLAGS (R5) ; Clear adapter mapping bit 
2$: ADPDISP SELECT=ADDR_BITS, - 
ADDRLIST=<<18 , 3$>>, - 
ADPADDR=RO 
BISW #1@UCB$V_DL_22BIT, - ; FOR MICROVAX II 22-BIT 
UCB$W_DL_FLAGS (R5) ; ADDRESSING AS WELL AS ADAPTER MAPPING 
3$: 
10$: MOVZWL UCB$W_STS(R5) ,R3 ;SAVE CURRENT UNIT STATUS 
BICW #UCB$M_ONLINE! UCB$M_VALID,- ;ASSUME OFFLINE/INVALID 
UCB$W_STS (R5) Mensuy 


; WAIT FOR CONTROLLER (6 SECONDS MAX) IF CHANNEL IS BUSY WITH ANOTHER UNIT 


MOVL UCB$L_CRB(R5) , RO ;GET CRB ADDRESS 
BBC #CRB$V_BSY , CRB$B_MASK(RO) ,20$ ;IF CLEAR - CHANNEL NOT BUSY 
TIMEDWAIT TIME=#600*1000, - ;6 SECOND WAIT LOOP 
INS1=<TSTB RL_CS(R4)>,- ;1S CONTROLLER READY 
INS2=<BLSS 15$>,-  ;IF LSS - YES 
DONELBL=15$ ; LABEL TO EXIT WAIT LOOP 
BLBC RO, 25$ ; TIME EXPIRED - EXIT 


; GET CURRENT DRIVE STATUS AND RESET DRIVE 
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20$ : MOVW #RL_DA_M_RST!- ;PUT RESET AND GET STATUS IN DAR 
RL_DA_M_STS!RL_DA_M_MRK,RL_DA(R4) ;... 
CLRL R1 ;CLEAR Ri FOR UNIT NUMBER 


INSV UCB$W_UNIT(R5) ,#8,#8,R1 ;GET UNIT NUMBER 
BISW3 R1,#F_GETSTATUS,RL_CS(R4) ;EXECUTE GET STATUS FUNCTION 


BSBW DL_WAIT ;WAIT FOR CONTROLLER 
TSTB RL_CS (R4) ;WAS CONTROLLER READY? 
BGEQ 25$ ;IF GEQ - NO 


’ 


; CLASSIFY DRIVE TYPE 


MOVL #°X2324C001 , - 


UCB$L_MEDIA_ID(R5) ;SET MEDIA IDENT "DL RLOi" 
BITW #RL_MP_M_TYP,RL_MP(R4) ;IS DRIVE TYPE = RLO2? 
BNEQ 30$ ;IF NEQ - YES 
MOVB S°#DT$_RLO1, - 

UCB$B_DEVTYPE (R5) ;SET RLO1 DEVICE TYPE 


MOVW #256 , UCB$W_CYLINDERS(R5) ;SET NUMBER OF RLO1 CYLINDERS 
MOVZWL #10240,UCB$L_MAXBLOCK(R5) ;SET MAX RLO1 BLOCK NUMBER 


BRB | 40$ 
25$: BRB 70$ ; BRANCH TO COMMON EXIT 
30$: MOVB S*#DT$_RLO2, - 
UCB$B_DEVTYPE(R5) ;SET RLO2 DEVICE TYPE 


MOVW #512, UCB$W_CYLINDERS(R5) ;SET NUMBER OF RLO2 CYLINDERS 
MOVZWL #20480,UCB$L_MAXBLOCK(R5) ;SET MAX RLO2 BLOCK NUMBER 
INCL UCB$L_MEDIA_ID(R5) ;SET MEDIA IDENT "DL RLO2" 
40$: BBC #UCB$V_VALID ,R3,60$ ; Branch around wait for drive to spin up 
; if the drive did NOT have a VALID 
; volume on it before POWER failure. 


; INITIALIZE UCB FIELDS AND WAIT FOR ONLINE UNITS TO SPIN UP 


45$: BITW #RL_CS_M_DRDY,RL_CS(R4) ; Is drive ready? 
BNEQ 50$ ;IF NEQ - YES 
JSB G* EXE$PWRTIMCHK ;IS MAX TIME EXCEEDED? 
BLBS RO, 45$ ;IF LBS - NO, STILL MORE TIME NEEDED 
BRB 60$ ;POWER UP TIME EXCEEDED 
50$: 


BISW #UCB$M_VALID ,UCB$W_STS(R5) ;SET UCB STATUS VOLUME VALID 
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Sam 


60$: 


65$: 
70$: 


ple Driver for the RL11, RLO1, and RLO2 


BBS #UCB$V_DL_MAPPING, - ; ADAPTER MAPPING? 
UCB$W_DL_FLAGS(R5) ,65$ ;IF BS YES 

MOVL UCB$L_CRB(R5) ,R1 ;GET CRB ADDRESS 

MOVL CRB$L_AUXSTRUC(R1) ,R2 ;MEMORY ALLOC FAILURE DURING CTL INIT? 

BEQL 70$ ;IF EQL YES, LEAVE OFFLINE 


MOVL R2,UCB$A_DL_BUF_VA(R5) ;SAVE BUFFER'S VIRTUAL ADDRESS 
EXTZV #VA$V_VPN,#VA$S_VPN,R2,R1;GET VIRTUAL PAGE NUMBER OF BUFFER 
MOVL G°MMG$GL_SPTBASE , RO ;GET BASE ADDRESS OF SPTS 

MOVL (RO) [R1] , RO ;GET THE PTE CONTENTS 

BICL3 #°C<VA$M_BYTE>,R2,R1 . ;GET BUFFER OFFSET (BAOO-BA08) 
ASSUME PTE$S_PFN GE 13 

INSV RO, #9 ,#13,R1 ;COPY BAOQ-BA21 

MOVL R1,UCB$A_DL_BUF_PA(R5) ;SAVE PHYSICAL ADDRESS OF BUFFER 
BISW #UCB$M_ONLINE, UCB$W_STS(R5) ;SET UCB STATUS VOLUME VALID 
RSB 

. PAGE 

-SBTTL DRIVER SPECIFIC SUBROUTINES 


; DL_WAIT - WAIT FOR CONTROLLER READY 


; INPUTS: 


R4 - DEVICE CSR ADDRESS 


; FUNCTIONAL DESCRIPTION: 


DL_WAIT: 


:++ 


THIS ROUTINE IS CALLED FROM THE DRIVER UNIT INITIALIZATION ROUTINE 
TO WAIT UNTIL THE RL11 CONTROLLER IS READY. TO PREVENT HANGING UP 
AT HIGH IPL, A MAXIMUM OF 30 USEC ELAPSES BEFORE CONTROL IS 
RETURNED TO THE CALLER. 


;WAIT FOR CONTROLLER READY 
MOVQ RO, - (SP) ;SAVE RO, Ri 
TIMEWAIT #3, #RL_CS_M_CRDY,RL_CS(R4) ,W 
MOVQ (SP)+,RO ;RESTORE RO, R1 
RSB ;RETURN TO UNIT INIT OR STARTIO 


. PAGE 
-SBTTL FDT ROUTINE - TEST TRANSFER BYTE COUNT ALIGNMENT 


; DL_ALIGN - FDT ROUTINE TO TEST XFER BYTE COUNT 


; FUNCTIONAL DESCRIPTION: 


THIS ROUTINE IS CALLED FROM THE FUNCTION DECISION TABLE DISPATCHER 
TO CHECK THE BYTE COUNT PARAMETER SPECIFIED BY THE USER PROCESS 
FOR AN EVEN NUMBER OF BYTES (WORD BOUNDARY) . 


; INPUTS: 

: R3 - IRP ADDRESS (I/0 REQUEST PACKET) 

: R4 - PCB ADDRESS (PROCESS CONTROL BLOCK) 

; R5 - UCB ADDRESS (UNIT CONTROL BLOCK) 

: R6 - CCB ADDRESS (CHANNEL CONTROL BLOCK) 

: R7 - BIT NUMBER OF THE I/O FUNCTION CODE 

‘ R8 - ADDRESS OF FDT TABLE ENTRY FOR THIS ROUTINE 

: 4 (AP) ~ ADDRESS OF FIRST FUNCTION DEPENDENT QIO PARAMETER 
; OUTPUTS: 


IF THE QIO BYTE COUNT PARAMETER IS ODD, THE I/O OPERATION IS 
TERMINATED WITH AN ERROR. IF IT IS EVEN, CONTROL IS RETURNED 
TO THE FDT DISPATCHER. 


DL_ALIGN : 
BLBS 
RSB 
10$: MOVZWL 
JMP 
. PAGE 
.SBTTL 


++ 
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;CHECK BYTE COUNT AT P1(AP) 


4(AP) ,10$ ;IF LBS'- ODD BYTE COUNT 

;EVEN - RETURN TO CALLER 
#SS$_IVBUFLEN , RO ;SET BUFFER ALIGNMENT STATUS 
G* EXE$ABORTIO ;ABORT 1/0 


START I/0 ROUTINE 


; DL_STARTIO - START I/O ROUTINE 


; FUNCTIONAL DESCRIPTION: 


; THIS FORK PROCESS IS ENTERED FROM THE EXECUTIVE AFTER AN I/O REQUEST 
i PACKET HAS BEEN DEQUEUED, AND PERFORMS THE FOLLOWING: 


; INPUTS: 


: R3 
; R5 


; IRP$L_MEDIA 


; OUTPUTS: 


RO 
R1 


- ACTIVATES THE DISK AFTER SETTING UCB FIELDS, OBTAINING 
UBA AND CONTROLLER RESOURCES, AND SETTING RL11 REGISTERS 


- WAITS FOR AN INTERRUPT 


- REGAINS CONTROL AFTER THE ISR SERVICES THE INTERRUPT, AND 
- REACTIVATES THE DISK IF THE ORIGINAL FUNCTION 
IS NOT YET COMPLETE, OR 
- COMPLETES THE I/0 REQUEST BY RELEASING RESOURCES, 
SETTING STATUS CODES, AND RETURNING TO THE EXECUTIVE. 


IRP ADDRESS (1/0 REQUEST PACKET) 
UCB ADDRESS (UNIT CONTROL BLOCK) 
PARAMETER LONGWORD (LOGICAL BLOCK NUMBER) 


- FIRST I/0 STATUS LONGWORD: STATUS CODE & BYTES XFERED 
- SECOND I/O STATUS LONGWORD: O FOR DISKS 


: THE I/O FUNCTION IS EXECUTED. 


; ALL REGISTERS EXCEPT RO-R4 ARE PRESERVED. 


DL_STARTIO: 


;START I/0 OPERATION 


: COMPUTE PHYSICAL MEDIA ADDRESS 


LBN = LBN * (SECTORS/BLOCK) 
LBN/(SECTORS/TRACK) = D + SECTOR 
D/(TRACKS/CYLINDER) = CYLINDER + TRACK 


; PREPROCESS UCB FIELDS 
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PREPROCESS : 
MOVL 


BBS 


MULL3 
MOVZBL 
CLRL 
EDIV 
MOVZBL 
EDIV 
MOVB 
MOVW 
10$: 
MOVB 


MNEGW 
CLRW 


CLRB 
MOVW 
EXTZV 


MOVB 
CMPR 
BNEQ 
MOVW 


20$: 
BICW 


BBC 


BISW 


: CENTRAL 


FDISPATCH: 
MOVL 
BBS 


BBS 


MOVZWL 
BRW 
CLRB 
MOVZBL 
CASE 


10$: 
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IRP$L_MEDIA(R3) , - ; Copy given MEDIA address (logical) 
UCB$L_MEDIA (R5) ; to the UCB. 

#IRP$V_PHYSIO, - ;IF SET - PHYSICAL I/O 
IRP$W_STS(R3) , 10$ 

#2, UCB$L_MEDIA(R5) , RO ;SCALE LBN IN RO 

UCB$B_SECTORS (R5) ,R2 ;GET NUMBER OF SECTORS PER TRACK 
Ri ;CLEAR HIGH PART OF DIVIDEND 
R2,RO,RO, UCB$L_MEDIA(R5) ; CALCULATE SECTOR NUMBER AND STORE 
UCB$B_TRACKS(R5) ,R2 ;GET NUMBER OF TRACKS PER CYLINDER 
R2,RO,RO,R1 ;CALCULATE TRACK AND CYLINDER 

Ri, UCB$L_MEDIA+14 (R5) ;STORE TRACK NUMBER 

RO , UCB$L_MEDIA+2(R5) ; STORE CYLINDER NUMBER 


UCB$B_ERTMAX (R5) , - ; INITIALIZE ERROR RETRY COUNT 

UCB$B_ERTCNT (R5) Ret 

UCB$W_BCNT(R5) ,UCB$W_BCR(R5) ;INIT NEG BYTES LEFT TO XFER 

UCB$W_DL_DPN (R5) ;CLEAR DATA PATH NO. FOR USE AS- 
;UBA RESOURCE ALLOCATION FLAG 

UCB$B_DL_DPPE(R5) ;CLEAR DATAPATH PURGE ERROR REGISTER 

IRP$W_FUNC(R3) ,UCB$W_FUNC(R5) ;SAVE FUNCTION CODE 

#IRP$V_FCODE, - ;EXTRACT I/O FUNCTION CODE 

#IRP$S_FCODE, IRP$W_FUNC(R3),R1 ;... 

R1, UCB$B_FEX (R5) ;STORE FUNCTION DISPATCH INDEX 

#T°$ SEEK ,R1 ;SEEK FUNCTION? 

20$ :IF NEQ - NO 

IRP$L_MEDIA(R3) , - -STORE CYLINDER ADDRESS 

UCB$W_DC (R5) Se ate 


#UCB$M_DIAGBUF , - 

UCB$W_DEVSTS (R5) ;CLR DIAGNOSTIC BUFFER PRESENT 
#IRP$V_DIAGBUF , - ;IF CLR - NO DIAG BUFFER 
IRP$W_STS(R3) ,FDISPATCH ;... 


#UCB$M_DIAGBUF , UCB$W_DEVSTS(R5) ;SET DIAG BUFFER PRESENT 


FUNCTION DISPATCH 


;FUNCTION DISPATCH 
;GET IRP ADDRESS 
;IF SET - PHYSICAL I/0 FUNCTION 


UCB$L_IRP(R5) ,R3 
#IRP$V_PHYSIO, - 
IRP$W_STS(R3) , 10$ 
#UCB$V_VALID, - 
UCB$W_STS(R5) ,10$ 
#SS$_VOLINV,RO 
RESETXFR 
UCB$B_DL_DCHEK (R5) 
UCB$B_FEX(R5) ,R3 


;IF SET - VOLUME SOFTWARE VALID 


;SET VOLUME INVALID STATUS 
;RESET BYTE COUNT AND EXIT 
;CLEAR DATA CHECK IN PROGRESS 
;GET FUNCTION DISPATCH INDEX 


R3, <- ;DISPATCH TO FUNCTION HANDLING ROUTINE 
UNLOAD, - ; UNLOAD 

SEEK , - ; SEEK 

NOP, - ; RECALIBRATE (unsupported) 
DRVCLR, - ; DRVCLR 

NOP, - ; RELEASE PORT (unsupported) 

NOP, - ; OFFSET HEADS (unsupported) 

NOP, - ; RETURN TO CENTER (unsupported) 
PACKACK , ~ ; PACK ACKNOWLEDGE 

NOP, - ; SEARCH (unsupported) 
WRITECHECK, - ; WRITE CHECK 

WRITEDATA, - ; WRITE DATA 

READDATA, - ; READ DATA 

NOP, - ; WRITE HEADER (unsupported) 
READHEAD , ~ ; READ HEADER 
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NOP, - 

NOP, - 

AVAILABLE- 

>, LIMIT=#CDF_UNLOAD 
NOP: 
SEEK: 
DRVCLR: 


DO_FUNCTION: 
EXFUNCL RETRYERR 
BRB NORMAL 


PACKACK : 
BISW #UCB$M_VALID, - 
UCB$W_STS (R5) 
BRB DO_FUNCTION 


UNLOAD : 
AVAILABLE: 
BICW #UCB$M_VALID, - 
UCB$W_STS (R5) 
BRB NORMAL 
WRITECHECK : 
READHEAD : 
BICW #I0$M_DATACHECK, - 
UCB$W_FUNC (R5) 
WRITEDATA : 
READDATA: 
EXFUNCL RETRYERR, F_SEEK 
MOVZBL UCB$B_FEX(R5) ,R3 
EXFUNCL RETRYERR 
; OPERATON COMPLETION 
NORMAL : 


MOVZWL #SS$_NORMAL,RO 
BRW FUNCXT 


RETRYERR : 
DECB UCB$B_ERTCNT (R5) 
BEQL FATALERR 
BRW FDISPATCH 


FATALERR : 
MOVZWL #SS$_VOLINV,RO 
BBS #RL_MP_V_VC, - 
UCB$W_DL_MP (R5) , FUNCXT 


MOVZWL #SS$_WRITLCK, RO 
BBC #RL_MP_V_WL, - 
UCB$W_DL_MP (R5) , 5$ 


BBS #RL_MP_V_WGE, - 

UCB$W_DL_MP (R5) , FUNCXT 
5$: MOVZWL #SS$_DATACHECK,RO ~ 

TSTB UCB$B_DL_DCHEK (R5) 

BEQL 10$ 

BBS #RL_CS_V_OPTI, - 
UCB$W_DL_CS(R5) , 10$ 

BBS #RL_CS_V_CRC, - 


UCB$W_DL_CS(R5) , FUNCXT 


; place holder 
; place holder 


; AVAILABLE 
;NO-OP 
; SEEK 


;DRIVE CLEAR (GET STATUS & RESET) 


;EXECUTE FUNCTION - RETRY IF FAILURE 
;SUCCESSFUL - EXIT WITH NORMAL STATUS 


;PACK ACKNOWLEDGE (GET STATUS & RESET) 
;Set software volume valid bit. 


;Then go do hardware function. 


; UNLOAD 
; AVAILABLE 


;Clear software volume valid bit. 
;and go complete operation without 
;any hardware interaction. 


;WRITE CHECK 
;READ HEADER 


;CLEAR DATA CHECK REQUEST- 
;TO PREVENT EXTRA WRITE CHECK 


; WRITE DATA 
;READ DATA 


;EXECUTE EXPLICIT SEEK - RETRY IF FAIL 


;GET FUNCTION DISPATCH INDEX 
; EXECUTE TRANSFER FUNCTION 


; SUCCESSFUL OPERATION COMPLETE 
;SET NORMAL COMPLETION STATUS 
;FUNCTION EXIT 


;RETRIABLE ERROR 
;ANY RETRIES LEFT? 


;IF EQL - NO 


;RETRY FUNCTION 


;UNRECOVERABLE ERROR 
; ASSUME VOLUME INVALID STATUS 
;IF SET - VOLUME INVALID 


peoee 


; ASSUME WRITE LOCK ERROR STATUS 
;IF CLR - VOLUME NOT WRITE LOCKED 


;IF SET - WRITE GATE ERROR 
;IF WL & WGE SET - WRITE LOCK ERROR 


;ASSUME DATA CHECK ERROR STATUS 
;WRITE CHECK IN PROGRESS? 


;IF EQL - NO 


;IF SET - NOT WRITE CHECK ERROR 


;IF SET - WRITE CHECK ERROR 
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10$: 


20$: 


FUNCXT: 


10$: 


20$: 


MOVZWL 
BBS 


MOVZWL 
BBS 


MOVZWL 


PUSHL 
JSB 
CMPB 
BGTRU 
CMPB 
BEQL 
MOVL 
ADDW3 


TSTW 
BEQL 
BBC 


RELDPR 
RELMPR 
BRB 
MOVL 


RELCHAN 


CLRL 
POPL 
REQCOM 
. PAGE 


#SS$_PARITY , RO ; ASSUME PARITY ERROR STATUS 

#RL_CS_V_CRC, - ;IF SET - CRC ERROR 

UCB$W_DL_CS(R5) ,FUNCXT ;OR DATAPATH PURGE ERROR 

#SS$_DRVERR , RO ; ASSUME DRIVE ERROR STATUS 

#RL_CS_V_DE, - ;IF SET - DRIVE ERROR 

UCB$W_DL_CS(R5),FUNCXT ;... 

#SS$_CTRLERR., RO ; ASSUME CONTROLLER ERROR STATUS 
;FUNCTION EXIT 

RO ;SAVE FINAL REQUEST STATUS 

G* IOC$DIAGBUF ILL ;FILL DIAGNOSTIC BUFFER IF PRESENT 

#CDF_WRITECHECK , UCB$B_FEX(R5) ;DRIVE RELATED FUNCTION? 

10$ ;IF GTRU - YES 

#CDF_AVAILABLE ,UCB$B_FEX(R5) = ;DRIVE RELATED FUNCTION? 

10$ ;IF EQL - YES 

UCB$L_IRP(R5) ,R3 ;RETRIEVE ADDRESS OF IRP 

UCB$W_BCR(R5) , - ;CALCULATE BYTES TRANSFERRED 

IRP$W_BCNT(R3),2(SP) —;.... 

UCB$W_DL_DPN (R5) ;ARE UBA RESOURCES ALLOCATED? 

20$ ;IF EQL-- NO 

#UCB$V_DL_MAPPING, - ; ADAPTER MAPPING? 


UCB$W_DL_FLAGS(R5),10$ ;IF BC NO 
;RELEASE DATA PATH 
;RELEASE MAP REGISTERS 
20$ ; JOIN COMMON CODE 
UCB$L_DL_SVAPTE(RS5) , - ;RESTORE ORIGINAL SVAPTE 
UCB$L_SVAPTE(R5) ; 


;RELEASE CHANNEL IF OWNED 
Ri ;CLEAR SECOND STATUS LONGWORD 
RO ;RETRIEVE FINAL REQUEST STATUS 


;COMPLETE REQUEST 


; FEXL - RL1i HARDWARE FUNCTION EXECUTION 


; THIS ROUTINE IS CALLED VIA A BSB WITH A BYTE IMMEDIATELY FOLLOWING THAT 

; SPECIFIES THE ADDRESS OF AN ERROR ROUTINE. ALL DATA IS ASSUMED TO HAVE BEEN 
; SET UP IN THE UCB BEFORE THE CALL. THE APPROPRIATE PARAMETERS ARE LOADED 

; INTO DEVICE REGISTERS AND THE FUNCTION IS INITIATED. THE RETURN ADDRESS 

; IS STORED IN THE UCB AND A WAIT FOR INTERRUPT IS EXECUTED. WHEN THE 

; INTERRUPT OCCURS, CONTROL IS RETURNED TO THE CALLER. 


; INPUTS: 


R3 
R5 


00(SP) 
04 (SP) 


FUNCTION TABLE DISPATCH INDEX 
DEVICE UNIT UCB ADDRESS 


RETURN ADDRESS OF CALLER 
RETURN ADDRESS OF CALLER'S CALLER 


IMMEDIATELY FOLLOWING INLINE AT THE CALL SITE IS A BYTE WHICH CONTAINS 
A BRANCH DESTINATION TO AN ERROR RETRY ROUTINE. 


; OUTPUTS: 
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THERE ARE FOUR EXITS FROM THIS ROUTINE: 


1. SPECIAL CONDITION - THIS EXIT IS TAKEN IF A POWER FAILURE OCCURS 


OR THE OPERATION TIMES OUT. IT IS A JUMP TO THE APPROPRIATE 
ERROR ROUTINE. 


2. FATAL ERROR - THIS EXIT IS TAKEN IF A FATAL CONTROLLER OR DRIVE 
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, ERROR OCCURS OR IF ANY ERROR OCCURS AND ERROR RETRY IS EITHER 
: INHIBITED OR EXHAUSTED. IT IS A JUMP TO THE FATAL ERROR EXIT 
: ROUTINE. 


: 3. RETRIABLE ERROR - THIS EXIT IS TAKEN IF A RETRIABLE CONTROLLER 
; OR DRIVE ERROR OCCURS AND ERROR RETRY IS NEITHER INHIBITED 
; NOR EXHAUSTED. IT CONSISTS OF TAKING THE ERROR BRANCH EXIT 
; SPECIFIED AT THE CALL SITE. 


; 4. SUCCESSFUL OPERATION - THIS EXIT IS TAKEN IF NO ERRORS OCCUR 
; DURING THE OPERATION. IT CONSISTS OF A RETURN INLINE. 


: IN ALL CASES IF AN ERROR OCCURS, AN ATTEMPT IS MADE TO LOG THE ERROR. 
: IN ALL CASES FINAL DEVICE REGISTERS ARE RETURNED VIA THE UCB. 


UCB$W_BCR(R5) = NEGATIVE BYTES REMAINING TO TRANSFER 


. PAGE 
FEXL: ;FUNCTION EXECUTOR 
POPL UCB$L_DPC (R5) ;SAVE DRIVER PC VALUE 
MOVB R3, UCB$B_CEX (R5) ;SAVE CASE INDEX 
MOVL UCB$L_CRB(R5) , RO ;GET ADDRESS OF PRIMARY CRB 
MOVL CRB$L_INTD+VEC$L_IDB(RO),R1 ;GET ADDRESS OF IDB 
CMPL R5, IDB$L_OWNER (R1) ;DOES THIS PROCESS OWN CHANNEL? 
BNEQ 10$ :IF NEQ - NO 
MOVL IDB$L_CSR(R1) ,R4 ;SET ASSIGNED CHANNEL CSR ADDRESS 
BRB 20$ ; 
10$: REQPCHAN ;REQUEST CHANNEL (RETURNS R4 = CSR ADR) 
20$: CASE R3,<- :DISPATCH TO PROPER FUNCTION ROUTINE 
IMMED , - -NO OPERATION 
IMMED , - ;UNLOAD VOLUME (NOP) 
POSIT, - ;SEEK CYLINDER 
IMMED , - ;RECALIBRATE (NOP) 
DRCLR, - ;DRIVE CLEAR (GET STATUS & RESET) 
IMMED , - ;RELEASE DRIVE (NOP) 
IMMED, - ;OFFSET HEADS (NOP) 
IMMED , ~ :RETURN TO CENTERLINE (NOP) 
DRCLR, - :PACK ACKNOWLEDGE 
IMMED, - ;SEARCH (NOP) 
> : 
BRW XFER : TRANSFER FUNCTION 
. PAGE 


; IMMEDIATE FUNCTION EXECUTION 
: FUNCTIONS iNCLUDE: 
; NO OPERATION, 


; DRIVE CLEAR, AND 
i PACK ACKNOWLEDGE 


; INPUTS: 

; R3 - CASE INDEX 
; R4 - CSR ADDRESS 
; R5 - UCB ADDRESS 


; FUNCTIONAL DESRIPTION: 


; INTERRUPTS ARE LOCKED OUT, THE APPROPRIATE FUNCTION IS INITIATED WITH 
; INTERRUPT ENABLE, AND A WAIT FOR INTERRUPT AND KEEP CHANNEL IS EXECUTED. 
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DRCLR: 


IMMED : 


;DRIVE CLEAR 
BISW #RL_DA_M_STS!- ;SET GETSTATUS,RESET,AND MARK IN DAR 
RL_DA_M_RST!RL_DA_M_MRK,RL_DA(R4) ;... 


; IMMEDIATE FUNCTION EXECUTION 
CKPWR SAVE_RO=NO ;DISABLE INTERRUPTS, CHECK POWER, - 

;AND PUT UNIT NUMBER IN R2<9:8> 
BISW3 R2,FTAB[R3] ,RL_CS(R4) ;MERGE UNIT WITH FNTN AND EXECUTE 


WFIKPCH RETREG, #2 ;WAIT FOR INTERRUPT 
IOFORK ;RETURN FROM ISR- 
;CREATE FORK PROCESS (&JSB BACK TO ISR) 
BRW RETREG ; 
. PAGE 


; POSITIONING FUNCTION EXECUTION 


FUNCTIONS INCLUDE: 


SEEK CYLINDER 


; INPUTS: 


R3 - CASE INDEX 
R4 ~ DEVICE CSR ADDRESS 
RS ~ UCB ADDRESS 


; FUNCTIONAL DESRIPTION: 


; THE CYLINDER DIFFERENCE WORD IS CALCULATED AND LOADED INTO THE DISK 
; ADDRESS REGISTER, INTERRUPTS ARE LOCKED OUT, AND THE SEEK FUNCTION 

; IS INITIATED WITHOUT INTERRUPT ENABLE. THE CONTROLLER IS THEN POLLED 
; FOR READY, AND DEVICE INTERRUPTS ARE ENABLED. 


; SINCE THE RLO1/RLO2 DO NOT ISSUE AN INTERRUPT UPON COMPLETION OF A 
; SEEK, OVERLAPPED SEEKS ARE NOT ATTEMPTED, AND ONE OF THE FOLLOWING IS 
; PERFORMED. 
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IF ONLY A SEEK FUNCTION IS BEING REQUESTED, A DUMMY READ HEADER 
FUNCTION IS ISSUED AND A WAITFOR INTERRUPT IS INITIATED. 

THE READ HEADER IS USED TO SIGNAL THE END OF THE SEEK, SINCE IT 
WILL ISSUE AN INTERRUPT SHORTLY (315 USEC AVG) AFTER THE SEEK IS 
COMPLETE. IT WILL ALSO SENSE FOR A TIMEOUT DURING THE SEEK. 


IF THE SEEK IS ASSOCIATED WITH A DATA TRANSFER REQUEST (RLO1/RLO2 
TRANSFER FUNCTIONS REQUIRE EXPLICIT SEEKS), THE PROGRAM KEEPS THE 
CHANNEL AND RETURNS TO FDISPATCH TO ISSUE THE TRANSFER REQUEST 
WHILE THE SEEK IS STILL IN PROGRESS. WHEN THE SEEK COMPLETES, THE 
RL1i1 CONTROLLER WILL BEGIN THE TRANSFER. 


POSIT: 
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;POSITIONING FUNCTION 


; OBTAIN CURRENT DISK ADDRESS 


; IF THERE HAS NOT BEEN A PREVIOUS TRANSFER DURING THIS REQUEST, 
; A READ HEADER IS EXECUTED TO DETERMINE THE CURRENT DISK ADDRESS. 


TSTW 
BEQL 
BICW3 
BRW 
5$: BRW 
10$: MOVZBL 
20$: CKPWR 


BISW3 


WFIKPCH 
IOFORK 
BBC 
DECB 
BNEQ 


MOVZBW 
CKPWR 
BISW3 


WF IKPCH 
IOFORK 
CKPWR 


BISW3 


WF IKPCH 
IOFORK 
BBC 
40$: 
: CLRB 
BRW 
50$: 
BICW3 


UCB$W_DL_DPN (R5) ;WAS THERE A PREVIOUS TRANSFER? 
10$ ;IF EQL - NO, READ HEADER 
#°077,UCB$W_DL_DA(R5),R1 ;PUT CURRENT CYL & SURFACE IN R1 
60$ ;CALCULATE DIFFERENCE WORD 

50$ ; CONTINUE 

#8 ,R3 ;SET READ HEADER RETRY COUNT IN R3 
SAVE_RO=NO ;DISABLE INTERRUPTS, CHECK POWER, - 


;AND PUT UNIT NUMBER IN R2<9:8> 
R2,#F_READHEAD!RL_CS_M_IE,- ;EXECUTE READ HEADER 
RL_CS(R4) oe 
40$ , #2 ;WAIT FOR INTERRUPT OR TIMEOUT 
;CREATE FORK PROCESS 
#RL_CS_V_CE,UCB$W_DL_CS(R5) ,5$ ;BR ON NO ERRORS 
R3 ;DECREMENT READ HEADER RETRY COUNT 
20$ ;IF NEQ - RETRY READ HEADER 
;IF EQL - READ HEADER RETRY EXHAUSTED - 
;TRY PREVIOUS TRACK 


#°X80!RL_DA_M_MRK, - ;LOAD REVERSE SEEK DIFFERENCE WORD 
RL_DA(R4) ae 
SAVE_RO=NO0 ;DISABLE INTERRUPTS, CHECK POWER, - 


;AND PUT UNIT NUMBER IN R2<9:8> 
R2,#F_SEEK!RL_CS_M_IE,- ;EXECUTE REVERSE SEEK 


RL_CS(R4) ‘oe 

40$ , #2 ;WAIT FOR SEEK TO BEGIN (INTERRUPT) 
;CREATE FORK PROCESS 

SAVE_RO=NO ;DISABLE INTERRUPTS, CHECK POWER, - 


;AND PUT UNIT NUMBER IN R2<9:8> 
R2,#F_READHEAD!RL_CS_M_IE,- ;TRY READ HEADER ON NEW TRACK 
RL_CS(R4) eas 
A0$ , #2 ;WAITFOR INTERRUPT OR TIMEOUT 

;CREATE FORK PROCESS 
#RL_CS_V_CE, UCB$W_DL_CS(R5) ,50$ ;BR IF NO HEADER ERROR 

;CANNOT READ CURRENT DISK ADDRESS 
UCB$B_ERTCNT (R5) ;CLEAR RETRY COUNT 
RETREG ; 

;FOUND CURRENT DISK ADDRESS 
#°077,UCB$W_DL_MP(R5),R1 ;PUT CURRENT CYL & SURFACE IN R1 


; CALCULATE CYLINDER DIFFERENCE WORD 


60$: CLRL 
INSV 
INSV 
CMPW 
BEQL 
BICB 
BICB 
SUBW 
BEQL 
BCC 
MNEGW 
BISW 

70$: INSV 
BISW3 


RO ;CLEAR RO FOR DESIRED ADDRESS 
UCB$W_DA+1(R5) ,#6,#1,RO ; INSERT DESIRED SURFACE IN RO<6> 
UCB$W_DC(R5) ,#7,#9,RO ;INSERT DESIRED CYLINDER IN RO<15:7> 


RO,R1 ;IS A SEEK NEEDED? 

80$ ;IF EQL - NO 

#°0177,R1 ;REMOVE SURFACE BIT 

#°0177 ,RO ;REMOVE SURFACE BIT 

RO,R1 ;SUBTRACT DESIRED FROM ACTUAL 

70$ ;IF EQL - ONLY CHANGE SURFACE 

70$ ;IF CC - ACTUAL>=DESIRED 

Ri,R1 ; ACTUAL<DESIRED, MAKE POSITIVE DIFF 
#4 ,R1i ;SET SIGN FOR MOVE TO CENTER OF DISK 


UCB$W_DA+1(R5) ,#4,#1,R1 ; INSERT SURFACE BIT 
#RL_DA_M_MRK,R1,RL_DA(R4) ;SET MARKER AND LOAD DIFFERENCE WORD 
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; EXECUTE SEEK 


CKPWR SAVE_RO=NO ;DISABLE INTERRUPTS, CHECK POWER, - 
;AND PUT UNIT NUMBER IN R2<9:8> 
BISW3 R2,#F_SEEK!RL_CS_M_IE,- ;EXECUTE SEEK FUNCTION 
RL_CS(R4) aay aie 
WFIKPCH 40$, #2 ;WAIT FOR SEEK TO BEGIN (INTERRUPT) 
IOFORK ;CREATE FORK PROCESS 


80$: CMPB #I0$_SEEK ,UCB$B_FEX(R5) ;IS SEEK ASSOCIATED WITH A TRANSFER? 


, 


BEQL 90$ ;IF EQL - NO, SEEK ONLY 


; RETURN FOR SEEK ASSOCIATED WITH A TRANSFER REQUEST 


INCL UCB$L_DPC (R5) ;ADJUST TO CORRECT RETURN ADDRESS 
JMP @UCB$L_DPC(R5) ;RETURN TO DRIVER FOR TRANSFER 


RETURN FOR SEEK ONLY REQUEST 


90$: CKPWR SAVE_RO=NO ;DISABLE INTERRUPTS, CHECK POWER, - 


;AND PUT UNIT NUMBER IN R2<9:8> 
BISW3 R2,#F_READHEAD!RL_CS_M_IE,- ;EXECUTE DUMMY READ HEADER 


RL_CS (R4) jes 
WFIKPCH RETREG , #2 ;WAIT FOR SEEK TO COMPLETE (INTERRUPT) 
IOFORK ;CREATE FORK PROCESS 
BRW RETREG ; 


. PAGE 


TRANSFER FUNCTION EXECUTION 
FUNCTIONS INCLUDE: 


WRITE CHECK 
WRITE DATA 
READ DATA, AND 
READ HEADER 


INPUTS: 
R3 - CASE INDEX 
R4 ~ DEVICE CSR ADDRESS 
R5 - UCB ADDRESS 


FUNCTIONAL DESCRIPTION: 


A UNIBUS DATAPATH IS REQUESTED FOLLOWED BY THE APPROPRIATE NUMBER OF MAP 
REGISTERS REQUIRED FOR THE TRANSFER. THE TRANSFER PARAMETERS ARE LOADED 
INTO THE DEVICE REGISTERS, INTERRUPTS ARE LOCKED OUT, THE FUNCTION IS 
INITIATED, AND A WAITFOR INTERRUPT AND KEEP CHANNEL IS EXECUTED. 


UPON RETURN FROM THE INTERRUPT SERVICE ROUTINE, IF THE TRANSFER IS 
COMPLETE, THE APPROPRIATE EXIT IS TAKEN. IF THE FUNCTION IS NOT COMPLETE 
TRANSFER PARAMETERS ARE UPDATED AND A RETURN TO FDISPATCH IS EXECUTED TO 
REISSUE SEEK AND TRANSFER FUNCTIONS WHILE KEEPING CHANNEL AND UBA 
RESOURCES. IF A DATA CHECK HAS BEEN REQUESTED, IT IS PERFORMED 

BEFORE RETURNING TO FDISPATCH. 
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XFER: 


; FIRST 


1$: 


; FIRST 


2$: 


» 


BBS 


MOVW 
MOVZWL 
MOVW 
ASHL 
MOVB 
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; TRANSFER FUNCTION EXECUTION 
#UCB$V_DL_MAPPING, - ; ADAPTER MAPPING? 
UCB$W_DL_FLAGS (R5) , 2$ ;BRANCH IF ADAPTER MAPPING. 
UCB$A_DL_BUF_PA(R5) , UCB$W_DL_SBA(R5) ;GET 1ST WORD OF BUFFER ADDR 
UCB$A_DL_BUF_PA+2(R5) ,RO;GET BITS 16:21 OF BUFFER ADDRESS 


RO, RL_BAE(R4) ;SET MEMORY EXTENSION BITS IN BAE 
#4,RO,RO ;PUT MEMORY EXTENSION BITS IN <5:4> 
RO, UCB$B_DL_XBA(R5) ;OF CSR 


TRANSFER OF THIS I/O REQUEST - ALLOCATE RESOURCES 


TSTW 
BNEQ 
CLRL 
CMPB 
BNEQ 
MOVAB 


MOVL 
MNEGW 
BRB 


UCB$W_DL_DPN (R5) ;RESOURCES ALREADY ALLOCATED? 

5$ ;IF NEQ - YES 

UCB$A_DL_MOVRTN(R5) ; ASSUME READ 

#CDF_WRITEDATA,R3 ;WRITE DATA? 

1$ ;IF NEQ NO 

G* IOC$MOVFRUSER , - ;SET MOVE ROUTINE ADDRESS FOR 
UCB$A_DL_MOVRTN(R5) ;18T PARTIAL WRITE 
UCB$L_SVAPTE(R5) , UCB$L_DL_SVAPTE(R5) ;SAVE SVAPTE FOR BUFFER COPY 
#1,UCB$W_DL_DPN(R5) ;SET FIRST XFER FLAG 

5$ ; JOIN COMMON CODE 


TRANSFER OF THIS I/O REQUEST - ALLOCATE RESOURCES 


TSTW 
BNEQ 
REQDPR 
REQMPR 
LOADUBA 
MOVL 
EXTZV 


MOVW 


MOVZWL 
INSV 


MOVW 
EXTZV 
MULB3 


UCB$W_DL_DPN (R5) ;UBA RESOURCES ALREADY ALLOCATED? 
5$ ;IF NEQ - YES 

;REQUEST DATAPATH 

;REQUEST MAP REGISTERS 

; LOAD UNIBUS MAP REGISTERS 
UCB$L_CRB(R5) ,R1 ;GET CRB ADDRESS 
#VEC$V_DATAPATH ,#VEC$S_DATAPATH,- ;EXTRACT DATAPATH NUMBER - 
CRB$L_INTD+VEC$B_DATAPATH(R1) , RO ;FOR UBA RESOURCE FLAG 


RO, UCB$W_DL_DPN(R5) ; INDICATE UBA RESOURCES ALLOCATED 
UCB$W_BOFF (R5) , RO ;GET BYTE OFFSET IN PAGE 
CRB$L_INTD+VEC$W_MAPREG(R1),- ;INSERT HIGH 7 BITS OF ADDRESS 
#9 , #7 , RO Sst 

RO, UCB$W_DL_SBA(R5) ;SET BUFFER ADDRESS 


#7 ,#2, CRB$L_INTD+VEC$W_MAPREG(R1),RO ;GET MEMORY EXTENSION BITS 
#16 ,RO,UCB$B_DL_XBA(R5) ;POSITION MEMORY EXTENSION BITS TO <5:4> 


; COMMON TRANSFER POINT 


; FOR A READ OPERATION WHEN NO ADAPTER MAPPING IS PRESENT EMPTY THE 
; INTERNAL PHYSICALLY CONTIGUOUS BUFFER FROM THE PREVIOUS READ TO THE 


; USER'S BUFFER. 


5$: 


BSBW 


DL_MOVE_TO_BUFFER ;COPY TO USER BUFFER 


; PUT BUFFER ADDRESS, WORD COUNT, AND DISK ADDRESS IN DEVICE REGISTERS 
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10$: 


MOVW UCB$W_DL_SBA(R5) , RL_BA(R4) 

MNEGW UCB$W_BCR(R5) ,- 
UCB$W_DL_PBCR(R5) 

MOVZBL UCB$B_SECTORS(R5) ,R2 

MOVZBL UCB$W_DA(R5) ,R1 

SUBW R1,R2 

MULW #256 , R2 

CMPW UCB$W_DL_PBCR(R5) ,R2 

BLEQU 10$ 

MOVW R2,UCB$W_DL_PBCR(R5) 


; FOR A WRITE OPERATION WHEN NO ADAPTER 


BSBW DL_MOVE_FROM_BUFFER 
MOVZBL UCB$B_DL_XBA(R5) ,RO 
BISW FTAB[R3] , RO 

DIVW3 #2,UCB$W_DL_PBCR(RS5) ,R2 
MNEGW R2,RL_MP(R4) 

MOVZBL UCB$W_DA(R5) ,R1 

INSV UCB$W_DA+1(R5) ,#6,#1,R1 
INSV UCB$W_DC(R5) ,#7,#9,R4 
MOVW R1i,RL_DA(R4) 


EXECUTE THE TRANSFER FUNCTION 


CKPWR 
BISW3 R2,RO,RL_CS(R4) 
WFIKPCH RETREG, #6 
IOFORK 

PURGE DATAPATH 
CLRB UCB$B_DL_DPPE(R5) 
JSB G* IOC$PURGDATAP 
BLBS RO, 20$ 
INCB UCB$B_DL_DPPE(R5) 


;SET BUFFER ADDRESS 

;GET BYTES LEFT TO TRANSFER AND - 

; ASSUME ONLY ONE TRANSFER NEEDED 
;GET SECTORS/SURFACE 

;GET DESIRED SECTOR 

;CALCULATE SECTORS LEFT ON SURFACE 
;CONVERT TO BYTES LEFT ON SURFACE 
;ARE ADDITIONAL TRANSFERS REQUIRED? 
;IF LEQU - NO 

;SET BYTE COUNT FOR THIS TRANSFER 


MAPPING IS PRESENT 
; FILL INTERNAL PHYSICALLY CONTIGUOUS BUFFER FROM THE USER'S BUFFER. 


;COPY FROM USER BUFFER 


;SET MEMORY EXTENSION BITS 
;MERGE XBA BITS WITH FUNCTION 
;CALCULATE TRANSFER WORD COUNT 
;SET TRANSFER WORD COUNT 


;PUT DESIRED SECTOR IN R1<5:0> 

; INSERT DESIRED SURFACE IN R1<6> 

; INSERT DESIRED CYLINDER IN R1<15:7> 
;SET DESIRED DISK ADDRESS 


;DISABLE INTERRUPTS, CHECK POWER, - 
;AND PUT UNIT NUMBER IN R2<9:8> 

; EXECUTE FUNCTION 

;WAITFOR INTERRUPT AND KEEP CHANNEL 
;RETURN HERE FROM ISR SAVING REGISTERS 
;CREATE FORK PROCESS (RETURN TO ISR) 
;RETURN HERE FROM ISR REI ROUTINE 


;CLEAR DATAPATH PURGE ERROR 
;PURGE DATAPATH 

; IF SET - NO PURGE ERRORS 
;SET DATAPATH PURGE ERROR 


SAVE UBA REGISTERS FOR UPDATE AND REGDUMP ROUTINES 
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; ADAPTER MAPPING? 


;SAVE DATAPATH REGISTER 
;EXTRACT LOW BITS OF FINAL MAP REG NO. 
;EXTRACT HI BITS OF FINAL MAP REG NO. 
; INSERT HIGH BITS OF FINAL MAP REGISTER 
; LEGAL MAP REGISTER NUMBER? 
;IF GEQ - YES 
;RESTRICT MAP REGISTER NUMBER 
;SAVE FINAL MAP REGISTER NUMBER 
;CLEAR PREVIOUS MAP REGISTER CONTENTS 
;CALCULATE PREVIOUS MAP REGISTER NUMBER 
;ANY PREVIOUS MAP REGISTER? 


;IF GTR - NO 
;SAVE PREVIOUS MAP REGISTER 


20$: BBC #UCB$V_DL_MAPPING, - 
UCB$W_DL_FLAGS(R5) ,30$ ;IF BC NO 
MOVL R1, UCB$L_DL_DPR(R5) 
EXTZV #9,#7,UCB$W_DL_BA(RS) ,RO 
EXTZV #4,#2,UCB$W_DL_CS(R5) ,R1 
INSV R1,#7,#2,RO 
CMPW #495 , RO 
BGEQ 25$ 
MOVZWL #495,RO 
25$: MOVL (R2) [RO] , UCB$L_DL_FMPR (R5) 
CLRL UCB$L_DL_PMPR(R5) 
DECL RO 
CMPV #VEC$V_MAPREG , #+VEC$S_MAPREG, - 
CRB$L_INTD+VEC$W_MAPREG(R3) ,RO ;... 
BGTR 30$ 
MOVL (R2) [RO] , UCB$L_DL_PMPR(R5) 
30$: BBC #RL_CS_V_CE, UCB$W_DL_CS(R5) , 40$ 


BRW RETREG 
40$: BLBC UCB$B_DL_DPPE(R5) ,45$ 
BRW RETREG 


;IF CLR - NO RL ERRORS 
;DEVICE ERROR 

;IF CLR - NO PURGE ERROR 

;PURGE ERROR 


; RETURN HEADER INFORMATION FOR READ HEADER FUNCTION 


45$: CMPB #CDF_READHEAD , UCB$B_CEX(R5) 
BNEQ DATACHECK 
PUSHL UCB$W_BCR(R5) 
PUSHL UCB$L_SVAPTE(R5) 
MOVAB UCB$W_DL_DB(R5) ,R1 
MOVL #6, R2 
CMPW R2,UCB$W_BCNT (R5) 
BLSSU 50$ 
MOVZWL UCB$W_BCNT(R5) ,R2 
50$: SUBW3 UCB$W_BCNT(R5) ,R2,UCB$W_BCR(R5) 
JSB G* IOC$MOVTOUSER 
POPL UCB$L_SVAPTE(R5) 
POPL UCB$W_BCR(R5) 


; PERFORM DATA CHECK, IF REQUESTED 


DATACHECK : 

BBC #IO$V_DATACHECK, - 
UCB$W_FUNC(R5) , UPDATE 

BBSC #0 , UCB$B_DL_DCHEK (R5) , - 
UPDATE 

INCB UCB$B_DL_DCHEK (R5) 

MOVZBL #10$_WRITECHECK ,R3 

BRW XFER 


;READ HEADER FUNCTION? 

;IF NEQ - NO 

;SAVE NEG BYTES REMAINING 

;SAVE ADDRESS OF PTE 

;SET ADDRESS OF INTERNAL BUFFER 
;SET NUMBER OF BYTES TO MOVE 
;ROOM FOR FULL HEADER? 

;IF LSSU - YES 

;SET LENGTH OF PARTIAL HEADER 
;CALCULATE TRANSFER BYTE COUNT 
;MOVE HEADER TO USER BUFFER 
;RESTORE ADDRESS OF PTE 
;RESTORE NEG BYTES REMAINING 


;DATACHECK AFTER PARTIAL TRANSFER 
;IF CLR - DATA CHECK NOT REQUESTED 


;IF SET - DATA CHECK ALREADY PERFORMED 


;SET DATA CHECK IN PROGRESS 
;SET CASE INDEX TO WRITE CHECK 
;BRANCH TO PERFORM WRITE CHECK 


; UPDATE BUFFER ADDRESS, CURRENT DISK ADDRESS, AND BYTES REMAINING 


; FOR NEXT TRANSFER 
UPDATE: 
BBC #UCB$V_DL_MAPPING, - 


UCB$W_DL_FLAGS (R5) , 10$ 


BICB3 #*XCF,UCB$W_DL_CS(RS5) ,- 
UCB$B_DL_XBA(R5) 
MOVW UCB$W_DL_BA(R5) , - 


UCB$W_DL_SBA(R5) 


; UPDATE TRANSFER PARAMETERS 
; ADAPTER MAPPING? 

;IF BC NO 

;SAVE MEMORY EXTENSION BITS 


; UPDATE SAVED BUFFER ADDRESS 


peee 
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10$: CLRB UCB$W_DA(R5) ; UPDATE DESIRED SECTOR TO ZERO 
ADDL3 #°0100,UCB$W_DL_DA(R5),R1 ;INCREMENT CYLINDER & SURFACE 
EXTZV = #6, #1,R1,R2 ; EXTRACT DESIRED DISK SURFACE 
MOVB R2, UCB$W_DA+1 (R5) ; UPDATE DESIRED DISK SURFACE 
EXTZV #7,#9,R1,R2 ; EXTRACT DESIRED DISK CYLINDER 
MOVW R2, UCB$W_DC(R5) ; UPDATE DESIRED DISK CYLINDER 
ADDW UCB$W_DL_PBCR(R5) , - ;UPDATE NEG BYTES REMAINING TO XFER 

UCB$W_BCR(R5) P4254 

BEQL RETREG ;IF EQL - TRANSFER COMPLETE 
BRW FDISPATCH ;MORE BYTES REMAINING - CONTINUE 


; GET STATUS AND RESET ERRORS 
RETREG: ;GET STATUS AND RESET ERRORS 


; FOR A READ OPERATION WHEN NO ADAPTER MAPPING IS PRESENT 
; EMPTY INTERNAL BUFFER INTO USER'S BUFFER FOR LAST READ 
BSBW DL_MOVE_TO_BUFFER ;MOVE LAST READ INTO USER'S BUFFER 
BITW #UCB$M_TIMOUT!UCB$M_POWER,- ; TIMEOUT OR POWERFAIL? 
UCB$L_STS (R5) ; 


BEQL o$ ;BR IF NO 
IOFORK ;ELSE, FORK 
O$: MOVW #RL_DA_M_STS! - ;PUT GET STATUS IN DAR 
RL_DA_M_MRK , RL_DA(R4) pan 
CLRL R2 ;CLEAR R2 FOR UNIT NUMBER 


INSV UCB$W_UNIT(R5) ,#8,#8,R2 ;GET UNIT NUMBER 
BISW3  R2,#F_GETSTATUS,RL_CS(R4) ;EXECUTE GET STATUS 
DEVICELOCK - 
LOCKADDR=UCB$L_DLCK(R5) ,- ;LOCK DEVICE ACCESS 
LOCKIPL=UCB$B_DIPL(R5),- ;RAISE IPL 


SAVIPL=- (SP) ,- ;SAVE CURRENT IPL 

PRESERVE=NO ;DON'T PRESERVE RO 
BSBW DL_WAIT ;WAIT FOR CONTROLLER 
MOVW RL_MP(R4) ,UCB$W_DL_MP(R5) ;RETRIEVE ERROR REGISTER 
MOVW #RL_DA_M_RST!- ;PUT GET STATUS & RESET IN DAR 


RL_DA_M_STS!RL_DA_M_MRK ,RL_DA(R4) ;... 
BISW3 R2,#F_GETSTATUS,RL_CS(R4) ;EXECUTE RESET 


BSBW DL_WAIT ;WAIT FOR CONTROLLER 
DEVICEUNLOCK - 
LOCKADDR=UCB$L_DLCK(R5) ,- ;UNLOCK DEVICE ACCESS 
NEWIPL=(SP) +, - ;RESTORE IPL 
PRESERVE=NO ;DON'T PRESERVE RO 


; DETERMINE EXIT - SPECIAL CONDITION, FATAL ERROR, RETRIABLE ERROR, OR SUCCESS 
CMPZV #0,#5,UCB$W_DL_MP(R5),- ;HEADS, BRUSHES, STATE OK? 
#RL_MP_M_BH!RL_MP_M_HO!RL_SLM ;... 


BEQL 1$ ;IF EQL - YES, ONLINE 
BICW #UCB$M_TIMOUT, UCB$W_STS(R5) ;CLEAR DEVICE TIME OUT 
MOVZWL #SS$_MEDOFL,RO ;SET MEDIUM OFFLINE STATUS 
BRW FUNCXT ; RETURN 
1$: BITW #UCB$M_POWER ! - ;POWER FAIL OR DEVICE TIMEOUT? 
UCB$M_TIMOUT,UCB$W_STS(R5) ;... 
BNEQ SPECOND ;IF NEQ - YES, SPECIAL CONDITION 
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BBS 
BBS 
BLBC 
2$: JSB 
BBS 
BBS 
BBC 
BBC 
BBS 
4$: BITW 


BNEQ 
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#RL_MP_V_VC ,UCB$W_DL_MP(R5) ,20$ ;IF SET - VOLUME INVALID 
#RL_CS_V_CE,UCB$W_DL_CS(R5),2$ ;IF SET - RL ERROR 
UCB$B_DL_DPPE(R5) ,10$ ;IF CLR - NO PURGE ERROR 

G*ERL$DEVICERR ;ALLOCATE AND FILL ERROR MESSAGE BUFFER 
#IO$V_INHRETRY ,UCB$W_FUNC(R5) ,20$ ;IF SET - RETRY INHIBITED 
#RL_CS_V_NXM, UCB$W_DL_CS(R5) ,20$ ;IF SET - NONEXISTENT MEMORY 
#RL_CS_V_DE, UCB$W_DL_CS(R5),5$ ;IF CLR - NO DRIVE ERRORS 
#RL_MP_V_WL,UCB$W_DL_MP(R5) ,4$ ;IF CLR - NOT WRITE LOCKED 
#RL_MP_V_WGE,UCB$W_DL_MP(R5),20$ ;IF WL & WGE SET - WL ERROR 


#RL_MP_M_WDE! - ;WRITE DATA ERROR, OR 
RL_MP_M_CHE! - ;CURRENT HEAD ERROR, OR 
RL_MP_M_WGE! - ;WRITE GATE ERROR, OR 
RL_MP_M_DSE, UCB$W_DL_MP(R5) ;DRIVE SELECT ERROR? 
20$ ;IF NEQ - YES 


; RETRIABLE ERROR EXIT 


’ 


5$: CVTBL 
ADDL 


@UCB$L_DPC(R5) , - (SP) ;GET BRANCH DISPLACEMENT 
(SP) +, UCB$L_DPC(R5) ;CALCULATE RETURN ADDRESS - 1 


; SUCCESSFUL OPERATION EXIT 


10$: INCL 
JMP 


UCB$L_DPC(R5) ;ADJUST TO CORRECT RETURN ADDRESS 
@UCB$L_DPC(R5) ;RETURN TO DRIVER 


; FATAL ERROR EXIT 


20$: BRW 


SPECOND: 
BBS 


JSB 
BICW 
MOVZWL 
DECB 
BEQL 
BRW 


RESETXFR : 
MOVL 
MNEGW 
BRW 


FATALERR ;FATAL ERROR EXIT 


; SPECIAL CONDITION EXIT (POWER FAILURE OR DEVICE TIMEOUT) 


#UCB$V_POWER, UCB$W_STS(R5) ,PWRFAIL ;IF SET - POWER FAILURE 
;IF CLR - DEVICE TIMEOUT 


G*ERL$DEVICTMO ;LOG DEVICE TIMEOUT 
#UCB$M_TIMOUT,UCB$W_STS(R5) ;CLEAR TIMEOUT STATUS 
#SS$_TIMEOUT , RO ;SET DEVICE TIMEOUT STATUS 
UCB$B_ERTCNT (R5) ; ANY ERROR RETRIES REMAINING? 
RESETXFR ;IF EQL - NO 
FDISPATCH ; RETURN 

;RESET TRANSFER BYTE COUNT 
UCB$L_IRP(R5) ,R3 ;GET ADDRESS OF I/0 PACKET 
IRP$W_BCNT(R3) , UCB$W_BCR(R5) ;RESET BYTE COUNT 
FUNCXT ; EXIT 
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PWRFAIL: 


50$: 


++ 


’ 


;POWER FAILURE 
BICW #UCB$M_POWER,UCB$W_STS(R5) ;CLEAR POWER FAILURE BIT 


TSTW UCB$W_DL_DPN (R5) ;ARE UCB RESOURCES ALLOCATED? 

BEQL 50$ ;IF EQL - NO 

BBC #UCB$V_DL_MAPPING, - ; ADAPTER MAPPING? 
UCB$W_DL_FLAGS(R5) ,50$ ;IF BC NO 

RELDPR ;RELEASE DATA PATH 

RELMPR ;RELEASE MAP REGISTERS 

RELCHAN ;RELEASE CHANNEL IF OWNED 

MOVL UCB$L_IRP(R5) ,R3 ;GET ADDRESS OF I/O PACKET 

MOVQ IRP$L_SVAPTE(R3) , - ;RESTORE TRANSFER PARAMETERS 
UCB$L_SVAPTE(R5) ae 

BRW PREPROCESS ;RETURN TO PREPROCESS UCB FIELDS 

. PAGE 


.SBTTL INTERRUPT SERVICE ROUTINE 


; DL$INT - RL141 INTERRUPT SERVICE ROUTINE 


; FUNCTIONAL DESCRIPTION: 


THIS ROUTINE IS ENTERED VIA A JSB INSTRUCTION WHEN AN INTERRUPT 
OCCURS ON AN RL11 DISK CONTROLLER. IF THE INTERRUPT IS NOT EXPECTED, 
THE UNSOLICITED INTERRUPT ROUTINE DISMISSES THE INTERRUPT. IF 

THE INTERRUPT IS EXPECTED, DEVICE REGISTERS ARE SAVED AND THE 
DRIVER IS CALLED AT ITS INTERRUPT RETURN ADDRESS. THE DRIVER FORKS, 
CAUSING A RETURN TO THIS ROUTINE, WHICH RESTORES GENERAL REGISTERS 
AND DISMISSES THE INTERRUPT. 


; INPUTS: 


OO(SP) - POINTER TO ADDRESS OF THE IDB 
04(SP) - SAVED RO 

O8(SP) - SAVED R1 

12(SP) - SAVED R2 

16(SP) - SAVED R3 

20(SP) - SAVED R4 

24(SP) - SAVED R65 
28(SP) - PC AT THE TIME OF THE INTERRUPT 
32(SP) - PSL AT THE TIME OF THE INTERRUPT 


; OUTPUTS: 
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DEVICE REGISTERS ARE SAVED, IPL IS LOWERED TO FORK LEVEL, THE 
INTERRUPT IS DISMISSED, ALL REGISTERS EXCEPT RO-R5 ARE PRESERVED. 


; INTERRUPT SERVICE ROUTINE 
MOVL @(SP)+,R3 ;REMOVE ADDRESS OF IDB FROM STACK 
ASSUME IDB$L_CSR EQ 0 
ASSUME IDB$L_OWNER EQ 4 


MOVQ (R3) ,R4 ;GET ADDRESS OF CSR AND UCB 

TSTL RS ;IS RS A ZERO 

BEQL DL_UNSOLNT ;IF EQL NO OWNER 

DEVICELOCK - 
LOCKADDR=UCB$L_DLCK(R5) ,- ;LOCK DEVICE ACCESS 
CONDITION=NOSETIPL, - ;DON'T CHANGE IPL 
PRESERVE=NO ;DON'T PRESERVE RO 

BBCC #UCB$V_INT, - ;IF CLR - INTERRUPT NOT EXPECTED 


UCB$W_STS(R5) ,40$ haces 
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CMPB #CDF_READHEAD, UCB$B_CEX(R5) ;READ HEADER FUNCTION? 
BNEQ 10$ -IF NEQ - NO 
MOVW RL_MP(R4) , UCB$W_DL_DB(R5) ;SAVE SECTOR HEADER INFORMATION 
MOVW RL_MP(R4) ,UCB$W_DL_DB+2(R5) ;... 
MOVW RL_MP(R4) , UCB$W_DL_DB+4 (R5) 
10$: MOVAB RL_CS(R4) ,R2 ‘GET ADDRESS OF CONTROL STATUS REGISTER 
MOVAB UCB$W_DL_CS(R5) ,R3 ;GET ADDRESS OF REGISTER SAVE AREA 
MOVW (R2)+, (R3) + ;SAVE CONTROL STATUS REGISTER 
MOVW (R2)+, (R3) + ;SAVE BUFFER ADDRESS REGISTER 
MOVW (R2)+, (R3)+ ;SAVE DISK ADDRESS REGISTER 
MOVW (R2)+, (R3)+ -SAVE MULTIPURPOSE REGISTER 
20$: MOVQ UCB$L_FR3(R5) ,R3 ;RESTORE DRIVER CONTEXT 
JSB @UCB$L_FPC(R5) ;CALL DRIVER AT INTERRUPT RETURN ADDRESS 
40$: DEVICEUNLOCK - 
LOCKADDR=UCB$L_DLCK(R5) ,- ;UNLOCK DEVICE ACCESS 
PRESERVE=NO ;DON'T PRESERVE RO 
DL_UNSOLNT: -UNSOLICITED INTERRUPT 
POPR #°M<RO,R1,R2,R3,R4,R5> ;RESTORE RO-R5 
REI :RETURN FROM INTERRUPT 
.PAGE 


-SBTTL REGISTER DUMP ROUTINE 


:++ 


; DL_REGDUMP - REGISTER DUMP ROUTINE 
FUNCTIONAL DESCRIPTION: 
; THIS ROUTINE IS CALLED TO SAVE THE DEVICE REGISTERS AND UBA RESOURCE 


; REGISTERS IN A SPECIFIED BUFFER. IT IS CALLED FROM THE DEVICE ERROR 
; LOGGING ROUTINE AND FROM THE DIAGNOSTIC BUFFER FILL ROUTINE. 


; INPUTS: 

: RO - ADDRESS OF REGISTER SAVE BUFFER 

: R4 - ADDRESS OF DEVICE CONTROL STATUS REGISTER (CSR) 
: R5 - ADDRESS OF UNIT CONTROL BLOCK (UCB) 

; OUTPUTS: 


; THE DEVICE AND UBA REGISTERS ARE SAVED IN THE SPECIFIED BUFFER. 
i RO CONTAINS THE ADDRESS OF THE NEXT EMPTY LONGWORD IN THE BUFFER. 
: ALL REGISTERS EXCEPT Ri AND R2 ARE PRESERVED. 


DL_REGDUMP : ;REGISTER DUMP ROUTINE 
MOVL #<RL_NUM_REGS+5>, (RO)+ ;INSERT NUMBER OF REGISTERS 
MOVAL UCB$W_DL_CS(R5) ,R1 ;GET ADDRESS OF SAVED DEVICE REGISTERS 
MOVZBL #RL_NUM_REGS ,R2 ;GET NUMBER OF DEVICE REGISTERS TO MOVE 
10$: MOVZWL (R1)+,(RO)+ ;DUMP REGISTER IN BUFFER 
SOBGTR R2,10$ ;IF GTR - STILL MORE TO MOVE 
MOVZWL (R1)+, (RO)+ ;DUMP DATAPATH NUMBER 
MOVL (R1)+, (RO) + ;DUMP DATAPATH REGISTER 
MOVL (R1)+, (RO) + ;DUMP FINAL MAP REGISTER 
MOVL (R1)+, (RO) + ;DUMP PREVIOUS MAP REGISTER 
MOVZBL (R1)+, (RO)+ ;DUMP DATAPATH PURGE ERROR REGISTER 
RSB ; RETURN 


E-27 


Sample Driver for the RL11, RLO1, and RLO2 


. PAGE 


.SBTTL MOVE TO USER BUFFER ROUTINE 


++ 


; DL_MOVE_TO_BUFFER - MOVE TO USER BUFFER 


; FUNCTIONAL DESCRIPTION: 


; THIS ROUTINE MOVES DATA BETWEEN THE PHYSICALLY CONTIGUOUS BUFFER AND 
; THE USER'S BUFFER. 


; INPUTS: 


R5 - UCB ADDRESS 


; OUTPUTS: 


; DATA MOVE BETWEEN THE PHYSICALLY CONTIGUOUS BUFFER AND THE USER'S BUFFER. 
: REGISTER'S RO,R1, AND R2 ARE DESTROYED 


DL_MOVE_TO_BUFFER : 


BBS 


CMPB 
BNEQ 
BBS 


TSTL 
BEQL 
MOVL 
MOVL 
MOVZWL 
JSB 
MOVL 
MOVAB 


10$: RSB 
20$: MOVAB 


RSB 
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#UCB$V_DL_MAPPING, - 
UCB$W_DL_FLAGS (R5) , 10$ 


;BUFFER MOVE ROUTINE 
; ADAPTER MAPPING? 
;IF BS YES NOTHING TO MOVE 


#CDF_READDATA, UCB$B_CEX(R5) ;READ DATA OPERATION? 


10$ 


#0 , UCB$B_DL_DCHEK (R5) , - 


10$ 
UCB$A_DL_MOVRTN (R5) 
20$ 
UCB$L_DL_BUFADR(R5) , RO 
UCB$A_DL_BUF_VA(R5) ,R1 
UCB$W_DL_PBCR(R5) ,R2 
@UCB$A_DL_MOVRTN (R5) 
RO, UCB$L_DL_BUFADR(R5) 
G* IOC$MOVTOUSERZ2, - 
UCB$A_DL_MOVRTN(R5) 


G* IOC$MOVTOUSER, - 
UCB$A_DL_MOVRTN(R5) 


; IF NEQ NOT A READ 

;DATA CHECK IN PROGRESS? 

;IF BS YES NOTHING TO MOVE 
;ANYTHING TO MOVE? 

;IF EQL NO 

;GET USER BUFFER POINTER 

;GET PHYSICALLY CONTIGUOUS BUFFER ADDRESS 
;GET NUMBER OF BYTES TO TRANSFER 
;CALL MOVE ROUTINE 

;SAVE INTERNAL BUFFER POINTER 
;SET NEXT MOVE ROUTINE TO BE USED 


; RETURN 
;SET NEXT MOVE ROUTINE TO BE USED 


; RETURN 


++ 


. PAGE 
.SBITL 
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MOVE FROM USER BUFFER ROUTINE 


; DL_MOVE_FROM_BUFFER - MOVE FROM USER BUFFER 


; FUNCTIONAL DESCRIPTION: 


; THIS ROUTINE MOVES DATA BETWEEN THE PHYSICALLY CONTIGUOUS BUFFER AND 


; THE USER'S BUFFER. 


; INPUTS: 


R5 - UCB ADDRESS 


; OUTPUTS: 


’ 


DATA MOVE BETWEEN THE PHYSICALLY CONTIGUOUS BUFFER AND THE USER'S BUFFER. 
REGISTER'S RO,R1, AND R2 ARE DESTROYED 


DL_MOVE_FROM_BUFFER: ;BUFFER MOVE ROUTINE 
BBS #UCB$V_DL_MAPPING, - ; ADAPTER MAPPING? 
UCB$W_DL_FLAGS(R5) ,10$ ;IF BS YES NOTHING TO MOVE 
CMPB #CDF_WRITEDATA, UCB$B_CEX(R5) ;WRITE DATA OPERATION? 
BNEQ 10$ -IF NEQ NOT A WRITE 
BBS #0, UCB$B_DL_DCHEK(R5),- ;DATA CHECK IN PROGRESS? 
10$ :IF BS YES NOTHING TO MOVE 
MOVL UCB$L_DL_BUFADR(R5),RO ;GET USER BUFFER POINTER . 
MOVL UCB$A_DL_BUF_VA(R5),R1  ;GET PHYSICALLY CONTIGUOUS BUFFER ADDRESS 
MOVZWL UCB$W_DL_PBCR(R5) ,R2 -GET NUMBER OF BYTES TO TRANSFER 
JSB @UCB$A_DL_MOVRTN(R5) -CALL MOVE ROUTINE 
MOVL RO,UCB$L_DL_BUFADR(R5) ;SAVE INTERNAL BUFFER POINTER 
MOVAB G“IOC$MOVFRUSERZ2, - ;SET NEXT MOVE ROUTINE TO BE USED 
UCB$A_DL_MOVRTN(R5) ; 
10$: RSB : RETURN 
DL_END: ; ADDRESS OF LAST LOCATION IN DRIVER 
.END 
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The following driver, XADRIVER, controls the DR11-W, a 16-bit parallel 


Sample Driver for the DR11—W and DRV11—WA 


DMA interface on UNIBUS systems. The driver also controls the DRV11- 


WA, a 16-bit parallel DMA interface on the Q22 bus. Operational details 


of these devices, as well as the capabilities controlled by the driver, can be 


found in the VMS-I/O User’s Reference Manual: Part II. 


You can find an online copy of the driver code (KADRIVER.MAR) in 
SYS$EXAMPLES. 


.TITLE XADRIVER - VAX/VMS DR11-W AND DRV11-WA DRIVER 
.IDENT 'X-15' 


5 FR A A RO A OK AG i HK A AE A A eH A OK 2 OK He EO RE A a 2 EO EO 2 2 a OK KK KK OK 


COPYRIGHT (c) 1978, 1980, 1982, 1984, 1985, 1986 BY 
DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASSACHUSETTS. 
ALL RIGHTS RESERVED. 


*¥ ¥ *¥ ee %¥ eK Ke KK KH He HK KF HHH H 


THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED 
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE 
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER 
COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY 
OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY 
TRANSFERRED . 


THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE 
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT 
CORPORATION. 


DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS 
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL. 


* *¥ eK Ke KK Ke Ke KF KF KF He He HK HK He % HK * 


AOA RO GO GR GOR IG GA I a kk a ak ak ak ak ak kk ak 
; 

++ 

: 


: FACILITY: 
: VAX/VMS Executive, I/O Drivers 
: ABSTRACT: 


: This module cortains the driver for the DRi1-W (Unibus) and 

: DRV11-WA (Q-bus). Since the driver was originally written for 

: the DR1i1-W, many inline comments refer to the "DR11-W" and "Unibus" 
: but apply equally well to the DRV11-WA and the Q-bus. 


; For DR11-W users: 
: This driver works for all hardware revision levels of 
; the DR1i1-W. 


; For DRV11-WA users: 
- This driver works for all hardware revision levels of 
: the DRV11-WA, up through and including CS Rev C. 


Sample Driver for the DR11—W and DRV11—WA 


BECAUSE ETCH REVISION E OF THE DRV11-WA 
PROVIDES SEVERAL CUSTOMER MODIFIABLE SETTINGS, 
IT IS VERY IMPORTANT THAT THE USERS OF THIS 
BOARD PROPERLY CONFIGURE IT TO BE BACKWARDS 
COMPATIBLE WITH EARLIER REVISIONS OF THE 


DRV11-WA. 


SPECIFICALLY, ON ETCH REVISION E 


BOARDS, JUMPERS W2, W3, AND W6 MUST BE INSTALLED. 


ENVIRONMENT : 


Kernel Mode, Non-paged 


.SBITL External and local symbol 


; External symbols 


$ACBDEF : 
$ADPDEF : 
$CRBDEF ; 
$DCDEF ; 
$DDBDEF : 
$DEVDEF ; 
$DPTDEF : 
$DYNDEF : 
$EMBDEF : 
$IDBDEF : 
$IODEF : 
$IPLDEF ; 
$IRPDEF : 
$PRDEF . 
$PRIDEF : 
$SSDEF ; 
$UCBDEF : 
$VECDEF : 
$XADEF : 


; Local symbols 


definitions 


AST control block 

Adapter control block 

Channel request block 

Device types 

Device data block 

Device characteristics 

Driver prologue table 

Dynamic data structure types 
EMB offsets 

Interrupt data block 

I/O function codes 

Hardware IPL definitions 

I/O request packet 

Internal processor registers 
Scheduler priority increments 
System status codes 

Unit control block 

Interrupt vector block 
Define device specific characteristics 


; Argument list (AP) offsets for device-dependent QIO parameters 


XA 
XA 
XA 


ey 


; Other 


, eek NO T E *4* 


0 ; 
4 : 
8 ; 
12 ; 
16 ; 
20 : 


constants 


_DEF_TIMEQUT 
_DEF_BUFSIZ 
_RESET_DELAY 


10 : 
65535 : 
<<2+9>/10> : 


First QIO parameter 
Second QIO parameter 
Third QIO parameter 
Fourth QIO parameter 
Fifth QIO parameter 
Sixth QIO parameter 


10 second default device timeout 

Default buffer size 

Delay N microseconds after RESET 
(rounded up to 10 microsec intervals) 


; DR11-W definitions that follow the standard UCB fields 
ORDER OF THESE UCB FIELDS IS ASSUMED 
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$DEFINI UCB 
. =UCB$L_DPC+4 


$DEF UCB$L_XA_ATTN ; Attention AST listhead 
-BLKL 1 

$DEF UCB$w_XA_CSRTMP ; Temporary storage of CSR image 
. BLKW 1 

$DEF UCB$w_XA_BARTMP ; Temporary storage of BAR image 
_BLKW i 

$DEF UCB$W_XA_CSR ; Saved CSR on interrupt 
._BLKW i 

$DEF UCB$W_XA_EIR ; Saved EIR on interrupt 
. BLKW 1 

$DEF UCB$w_XA_IDR ; Saved IDR on interrupt 
. BLKW 1 

$DEF UCB$W_XA_BAR ; Saved BAR register on interrupt 
. BLKW 1 

$DEF UCB$W_XA_WCR ; Saved WCR register on interrupt 
. BLKW 1 

$DEF UCB$W_XA_ERROR ; Saved device status flag 
. BLKW 1 

$DEF UCB$L_XA_DPR ; Data Path Register contents 
-_BLKL i 

$DEF UCB$L_XA_FMPR ; Final Map Register contents 
-_BLKL 1 

$DEF UCB$L_XA_PMPR ; Previous Map Register contents 
-BLKL 1 

$DEF UCB$W_XA_DPRN ; Saved Datapath Register Number 
.BLKW 1 - ; And Datapath Parity error flag 

$DEF UCB$W_XA_BAETMP ; Temporary storage of BAE (DRV11-WA 
-_BLKW 1 ; only) 

$DEF UCB$W_XA_BAE ; Saved BAE register (DRV11-WA only) 
. BLKW 1 


; Bit positions for device-dependent status field in UCB 


$VIELD UCB,0,<- ; UCB device specific bit definitions 
<ATTNAST, ,M>,- ; ATIN AST requested 
<UNEXPT, ,M>,- ; Unexpected interrupt received 
<IGNORE_UNEXPT, ,M>,- ; Ignore initial interrupt on DRV11-WA 
> 
UCB$K_SIZE=. 


$DEFEND UCB 


; Device register offsets from CSR address 


$DEFINI XA ; Start of DR11-W definitions 
$DEF XA_WCR ; Word count 
. BLKW al 
$DEF XA_BAR ; Buffer address 
$DEF XA_BAE ; Buffer address extension (DRV11-WA) 
. BLKW 1 
$DEF XA_CSR ; Control/status 


; Bit positions for device control/status register 


$EQULST XA$K_,,0,1,<- ; Define CSR FNCT bit values 
<FNCT1 , 2>- 
<FNCT2, 4>- 
<FNCT3, 8>- 
<STATUSA, 2048>- ; Define CSR STATUS bit values 


<STATUSB , 1024>- 
<STATUSC , 512>- 
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$DEF 


; Bit positions 


$DEF 
$DEF 


$VIELD XA_CSR,0,<- : 
<GO, ,M>,- : 
<FNCT,3,M>,- ; 
<XBA,2,M>,- : 
<IE, ,M>,- : 
<RDY, ,M>,- ; 
<CYCLE, ,M>, - ; 
<STATUS ,3,M>,- : 
<MAINT, ,M>,- ; 
<ATTN, ,M>,- ; 
<NEX, ,M>,- ; 
<ERROR, ,M>, - ; 

> 


$VIELD XA_BAE,0,<- : 
<MSB_ADDR ,6,M>, - ; 
<,9,>,- 
<CS_REV_C, ,M>,- : 
> 


XA_EIR ; 


$VIELD XA_EIR,0,<- : 
<REGFLG, ,M>, - : 
<SPARE,7,M>, - ; 
<BURST, ,M>, - i 
<DLT, ,M>,- : 
<PAR, ,M>,- ; 
<ACLO, ,M>,- ; 
<MULTI, ,M>,- ; 
<ATTN, ,M>,- ; 
<NEX, ,M>,- ; 
<ERROR, ,M>, - ; 


BLKW 1 


XA_IDR ; 
XA_ODR ; 
-BLKW 1 


$DEFEND XA ; 


.SBTTL Device Driver Tables 


; Driver prologue table 


Control/status register 
Start device 

CSR FNCT bits 

Extended address bits 
Enable interrupts 

Device ready for command 
Starts slave transmit 

CSR STATUS bits 

Maintenance bit 

Status from other processor 
Nonexistent memory flag 
Error or external interrupt 


Extended bus address register 
Qbus physical address <22:16> 


true if DRV11i-WA CS Rev C 


Error information register 


for error information register 


Error information register 

Flags whether EIR or CSR is accessed 
Unused - spare 

Burst mode transfer occurred 
Timeout for successive burst xfer 
Parity error during DATI/P 

Power fail on this processor 
Multi-cycle request error 

ATTN - same as in CSR 

NEX - same as in CSR 

ERROR - same as in CSR 


Input Data Buffer register 
Output Data Buffer register 


End of DR11-W definitions 
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DPTAB - ; 
END=XA_END, - ; 
ADAPTER=UBA , - ; 
FLAGS=DPT$M_SVP, - ; 
UCBSIZE=UCB$K_SIZE, - ; 
NAME=XADRIVER i 

DPT_STORE INIT : 

DPT_STORE UCB ,UCB$B_FLCK ,B,SPL$C_IOLOCK8 

DPT_STORE UCB,UCB$B_DIPL,B,22 : 

DPT_STORE UCB ,UCB$L_DEVCHAR,L,<-~- : 
DEV$M_AVL! - i 
DEV$M_RTM! - ; 
DEV$M_ELG! - : 
DEV$M_IDV! - ; 
DEV$M_ODV> ; 


DPT_STORE UCB ,UCB$B_DEVCLASS ,B, DC$_REALTIME i 


DPT_STORE UCB,UCB$B_DEVTYPE,B,DT$_DR11W ; 

DPT_STORE UCB,UCB$W_DEVBUFSIZ,W, - : 
' XA_DEF_BUFSIZ 

DPT_STORE REINIT ; 


DPT_STORE DDB,DDB$L_DDT,D, XA$DDT ; 
DPT_STORE CRB,CRB$L_INTD+4,D,- : 
XA_INTERRUPT 
DPT_STORE CRB,CRB$L_INTD+VEC$L_INITIAL, -; 
D,XA_CONTROL_INIT . ' 
DPT_STORE END : 


; Driver dispatch table 


DDTAB - ; 
DEVNAM=XA, - ; 
START=XA_START, - 
FUNCTB=XA_FUNCTABLE, - : 
CANCEL=XA_CANCEL, - ; 
REGDMP=XA_REGDUMP, - ; 
DIAGBF=<<15*4>+<<3+5+1>%4>>, - : 


DPT-creation macro 

End of driver label 
Adapter type 

Allocate system page table 
UCB size 

Driver name 

Start of load 


; initialization table 


; Device fork IPL 
Device interrupt IPL 
Device characteristics 
Available 
Real Time device 
Error Logging enabled 
input device 
output device 
Device class 
Device Type 
Default buffer size 


Start of reload 
initialization table 
Address of DDT 
Address of interrupt 


; service routine 


Address of controller 
initialization routine 
End of initialization 
tables 


DDT-creation macro 
Name of device 


; Start I/O routine 


FDT address 

Cancel I/0 routine 
Register dump routine 
Diagnostic buffer size 


ERLGBF=<<15*4>+<1*4>+<EMB$L_DV_REGSAV>> ; Error log buffer size 


; Function dispatch table 


XA_FUNCTABLE: ; 
FUNCTAB ,- ; 


FDT for driver 
Valid I/O functions 


<READPBLK , READLBLK , READVBLK , WRITEPBLK , WRITELBLK , WRITEVBLK, - 
SETMODE , SETCHAR , SENSEMODE , SENSECHAR> 


FUNCTAB , ; ; 
FUNCTAB XA_READ_WRITE, - ; 


No buffered functions 
Device-specific FDT 


<READPBLK , READLBLK , READVBLK , WRITEPBLK , WRITELBLK , WRITEVBLK> 


FUNCTAB 
FUNCTAB 
FUNCTAB 
FUNCTAB 


.SBTTL 


+EXE$READ , <READPBLK , READLBLK , READVBLK> 
+EXE$WRITE, <WRITEPBLK , WRITELBLK , WRITEVBLK> 
XA_SETMODE , <SETMODE , SETCHAR> 
+EXE$SENSEMODE , <SENSEMODE , SENSECHAR> 


XA_CONTROL_INIT, Controller initialization 


Sample Driver for the DR11—W and DRV11—WA 


++ 
; XA_CONTROL_INIT, Called when driver is loaded, system is booted, or 
; power failure recovery. 


; Functional Description: 


: 1) Allocates the direct data path permanently 

: 2) Assigns the controller data channel permanently 
; 3) Clears the Control and Status Register 

: 4) If power recovery, requests device time-out 


; Inputs: 


: R4 address of CSR 
: R5 address of IDB 
: R6 = address of DDB 
: R8 address of CRB 


; Outputs: 


; VEC$V_PATHLOCK bit set in CRB$L_INTD+VEC$B_DATAPATH 
; UCB address placed into IDB$L_OWNER 


, 


XA_CONTROL_INIT: 


MOVL IDB$L_UCBLST(R5) , RO ; Address of UCB 
MOVL RO, IDB$L_OWNER (R5) ; Make permanent controller owner 
BISW #UCB$M_ONLINE , UCB$W_STS (RO) 

; Set device status "on-line" 


ADPDISP SELECT=ADAP_MAPPING, - ; Check for adapter mapping 
ADDRLIST=<<YES , 1$>>, - 
CRBADDR=R8, - 
SCRATCH=R1 
BUG_CHECK UNSUPRTCPU, FATAL ; DRV11-WA not supported on non-mapping adapter 
1$: ADPDISP SELECT=QBUS, - ; Check for QBUS machine 
ADDRLIST=<<NO, 9$>>, - 
ADPADDR=R1i 
MOVB #DT$_XA_DRV11WA, - ; If this is a Q-bus, then this is 
UCB$B_DEVTYPE (RO) ; a DRV11-WA rather than a DR11-W. 


; DRV11-WAs at CS revision B and earlier incorrectly generated an interrupt 
; whenever the Interrupt Enable control bit (IE) underwent a low to high 
; transition. This phenomenon does not occur in boards at CS revision C. 


; To account for this unsoliciated interrupt, IGNORE_UNEXPT is set at 

; initialization for all DRV11-WAs at CS revisions prior to C. When this 
; bit is set, the next unexpected interrupt (as determined by the INT bit 
; in UCB status word, which is set whenever an 1/0 request is outstanding) 
; is discarded. The IGNORE_UNEXPT flag is necessary because driver 

; initialization occurs at a different IPL from the interrupt handling 


; routine. 
BICW #UCB$M_IGNORE_UNEXPT,- ; start out assuming this is a 
UCB$W_DEVSTS (RO) ; CS Rev C DRV11-WA 
TSTW XA_BAR(R4) ; BAR and BAE share the same physical 
MOVW XA_BAE(R4) ,R1 ; address -- they must be read in order. 
BBS #XA_BAE$V_CS_REV_C,R1,9$ ; branch around if CS Rev C 
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; BAE<15> is always set if the DRV11-WA is at CS Rev C or later. 


BISW #UCB$M_IGNORE_UNEXPT,- ; set flag so all interrupts are 
UCB$W_DEVSTS (RO) ; discarded until further notice 


; If powerfail has occurred and device was active, force device timeout. 
; The user can set his own timeout interval for each request. Timeout 
; is forced so a very long timeout period will be short circuited. 


9$: BBS #UCB$V_POWER , UCB$W_STS (RO) , 10$ 
; Branch if powerfail 
BISB #VEC$M_PATHLOCK , CRB$L_INTD+VEC$B_DATAPATH (R8) 
; Permanently allocate direct datapath 
10$: BSBW XA_DEV_HWRESET 
RSB ; Done 


.SBTTL XA_READ_WRITE, FDT for device data transfers 


++ 
; XALREAD_WRITE, FDT for READLBLK, READVBLK , READPBLK , WRITELBLK , WRITEVBLK , 
; WRITEPBLK 


; Functional description: 


: 1) Rejects QUEUE I/O's with odd transfer count 

: 2) Rejects QUEUE I/O's for BLOCK MODE request to UBA Direct Data 
; PATH on odd byte boundary 

; 3) Stores request timeout count specified in P3 into IRP 

; 4) Stores FNCT bits specified in P4 into IRP 

; 5) Stores word to write into ODR from P5 into IRP 

; 6) Checks block mode transfers for memory modify access 


; Inputs: 

; R3 = Address of IRP 

: R4 = Address of PCB 

; R5 = Address of UCB 

: R6 = Address of CCB 

; R8 = Address of FDT routine 

: AP = Address of Pi 

: Pi = Buffer Address 

: P2 = Buffer size in bytes 

: P3 = Request timeout period (conditional on IO$M_TIMED) 
; P4 = Value for CSR FNCT bits (conditional on IO$M_SETFNCT) 
: P5 = Value for ODR (conditional on IO$M_SETFNCT) 

: P6 = Address of Diagnostic Buffer 

; Outputs: 


; RO = Error status if odd transfer count 
: IRP$L_MEDIA = Timeout count for this request 
: IRP$L_SEGVBN = FNCT bits for DR1i-W CSR and ODR image 


XA_READ_WRITE: 


; The IO$M_INHERLOG ("inhibit error logging") function modifier was not 

; intended to be used by this driver. However, since the definition for 

; the IO$M_RESET modifier used to be the same as that for IO$M_INHERLOG, 

; the error logging routine incorrectly used the IO$M_RESET bit to 

; determine whether it should log errors. To solve this problem, the 

; definition for IO$M_RESET was changed. For the sake of old programs, we 
; Manually move the RESET bit to its new location. 


Sample Driver for the DR11—W and DRV11—WA 


BBCC 
BISW 


1$: BLBC 
2$: MOVZWL 
5$: JMP 
10$: MOVZWL 
MOVL 
BBS 
MOVL 


15$: BBC 
EXTZV 
CMPB 


BEQL 
CMPB 
BEQL 
MOVZWL 
BRB 
20$: EXTZV 
ASHL 
MOVW 


#IO$V_INHERLOG , IRP$W_FUNC(R3) , 1$ 
; Branch if old reset bit not set 
#IO$M_RESET , IRP$W_FUNC (R3) 
; Set new reset bit 


P2 (AP) ,10$ ; Branch if transfer count even 
#SS$_BADPARAM , RO ; Set error status code 
G*EXE$ABORTIO ; Abort request 

IRP$W_FUNC(R3) ,R1 ; Fetch I/0 Function code 
P3(AP),IRP$L_MEDIA(R3) ; Set request specific timeout count 
#IO$V_TIMED ,R1,15$ ; Branch if timeout specified 


#XA_DEF_TIMEOUT , IRP$L_MEDIA(R3) 

; Else set default timeout value 
#IO$V_DIAGNOSTIC,R1,20$ ; Branch if not maintenance request 
#IO$V_FCODE,#I0$S_FCODE,R1,R1 ; AND out all function modifiers 
#10$_READPBLK, Ri ; If maintenance function, must be 

; physical I/O read or write 


20$ 

#10$_WRITEPBLK ,R1 

20$ 

#SS$_NOPRIV , RO ; No privilege for operation 
5$ -; Abort request 

#0 ,#3,P4(AP) ,RO ; Get value for FNCT bits 


#XA_CSR$V_FNCT,RO,IRP$L_SEGVBN(R3) ; Shift into position for CSR 
P5(AP) , IRP$L_SEGVBN+2(R3) ; Store ODR value for later 


; If this is a block mode transfer, check buffer for modify access 
; whether or not the function is read or write. The DRii-W does 

; not decide whether to read or write, the user's device does. 

; For word mode requests, return to read check or write check. 


; If this is a BLOCK MODE request and the UBA Direct Data Path is 
; in use, check the data buffer address for word alignment. If buffer 
; 1s not word aligned, reject the request. 


BBS 
BBS 
BLBS 


25$: JMP 
30$: RSB 


.SBTTL 


#IO$V_WORD, IRP$W_FUNC(R3) ,30$ 

; Branch if word mode transfer 
#XA$V_DATAPATH , UCB$L_DEVDEPEND (R5) , 25$ 

; Branch if Buffered Data Path in use 


P1(AP) ,2$ ; DDP, branch on bad alignment 
G*EXE$MODIFY ; Check buffer for modify access 
; Return 


XA_SETMODE, Set Mode, Set characteristics FDT 


Sample Driver for the DR11—W and DRV11—WA 


++ 


; XA_SETMODE, FDT routine to process SET MODE and SET CHARACTERISTICS 

; Functional description: 

; If IO$M_ATTNAST modifier is set, queue attention AST for the device. 
' If IO$M_DATAPATH modifier is set, queue packet. 

: Else, finish I/O. 


; Inputs: 

; R3 = I/0 packet address 

: R4 = PCB address 

: R5 = UCB address 

; R6 = CCB address 

: R7 = Function code 

: AP = QIO Parameter list address 
; Outputs: 


i If IO$M_ATTNAST is specified, queue AST on UCB attention AST list. 
: If IO$M_DATAPATH is specified, queue packet to driver. 
; Else, use exec routine to update device characteristics. 


XA_SETMODE: | 
MOVZWL IRP$W_FUNC(R3) , RO ; Get entire function code 
BBC #IO$V_ATTNAST , RO, 20$ ; Branch if not an ATTN AST 


; Attention AST request 
PUSHR #°M<R4,R7> 


MOVAB UCB$L_XA_ATTN(R5) ,R7 ; Address of ATTN AST control block list 
JSB G* COM$SETATTNAST ; Set up attention AST 

POPR #°M<R4,R7> 

BLBC RO, 50$ ; Branch if error 


BISW #UCB$M_ATTNAST , UCB$W_DEVSTS (R5) 
; Flag ATTN AST expected. 
BBC #UCB$V_UNEXPT , UCB$W_DEVSTS(R5) , 10$ 
; Deliver AST if unsolicited interrupt 
BSBW DEL_ATTNAST 
10$: MOVZBL #SS$_NORMAL, RO ; Set status 
JMP G*EXE$FINISHIOC ; That's all for now (clears R1) 


; If modifier IO$M_DATAPATH is set, 
; queue packet. The data path is changed at driver level to preserve 
; order with other requests. 


20$: BBS S“#IO$V_DATAPATH,RO,30$ ; If BDP modifier set, queue packet 
JMP G* EXE$SETCHAR ; Set device characteristics 


; This is a request to change data path useage, queue packet 


30$: CMPL #1I0$_SETCHAR , R7 ; Set characteristics? 
BNEQ 45$ ; No, must have the privilege 
JMP G* EXE$SETMODE ; Queue packet to start I/0 


: Error, abort I0 


45$: MOVZWL #SS$_NOPRIV,RO ; No priv for operation 
50$: CLRL R1 
JMP G*EXE$ABORTIO ; Abort IO on error 


Sample Driver for the DR11—W and DRV11—WA 


.SBTTL XA_START, Start I/0 routines 
++ 
; XA_START - Start a data transfer, set characteristics, enable ATTN AST. 


; Functional Description: 
: This routine has two major functions: 


; 1) Start an I/O transfer. This transfer can be in either word 

; or block mode. The FNCIN bits in the DR11-W CSR are set. If 
i the transfer count is zero, the STATUS bits in the DRi1-W CSR 
; are read and the request completed. 

: 2) Set Characteristics. If the function is change data path, the 
; new data path flag is set in the UCB. 


; Inputs: 

: R3 = Address of the I/0 request packet 

; RS = Address of the UCB 

; Outputs: 

; RO = final status and number of bytes transferred 

; Ri = value of CSR STATUS bits and value of input data buffer register 


; Device errors are logged 
; Diagnostic buffer is filled 


.ENABL LSB 
XA_START: 
; Retrieve the address of the device CSR 


ASSUME IDB$L_CSR EQ 0 
MOVL UCB$L_CRB(R5) , R4 ; Address of CRB 
MOVL @CRB$L_INTD+VEC$L_IDB(R4) ,R4 

; Address of CSR 


; Fetch the I/O function code 


MOVZWL IRP$W_FUNC(R3) ,Ri ; Get entire function code 
MOVW Ri , UCB$W_FUNC(R5) ; Save FUNC in UCB for Error Logging 
EXTZV #IO$V_FCODE,#I0$S_FCODE,R1,R2 ; Extract function field 


; Dispatch on function code. If this is SET CHARACTERISTICS, we will 
; select a data path for future use. 

; If this is a transfer function, it will either be processed in word 
; or block mode. 


CMPB #1I0$_SETCHAR , R2 ; Set characteristics? 
BNEQ 3$ 
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++ 


; SET CHARACTERISTICS - Process Set Characteristics QIO function 


; INPUTS: 


XA_DATAPATH bit in Device Characteristics specifies which data path 
; to use. If bit is a one, use buffered data path. If zero, use 
: direct datapath. 


; OUTPUTS: 


: CRB is flagged as to which datapath to use. 

; DEVDEPEND bits in device characteristics is updated 
XA_DATAPATH = 1 -> buffered data path in use 
: XA_DATAPATH = 0 -> direct data path in use 


MOVL UCB$L_CRB(R5) , RO ; Get CRB address 
MOVQ IRP$L_MEDIA(R3) , UCB$B_DEVCLASS(R5) ; Set device characteristics 
BISB #VEC$M_PATHLOCK , CRB$L_INTD+VEC$B_DATAPATH (RO) 
; Assume direct datapath 
BBC #XA$V_DATAPATH , UCB$L_DEVDEPEND(R5) ,2$ ; Were we right? 
BICB #VEC$M_PATHLOCK , CRB$L_INTD+VEC$B_DATAPATH(RO) ; Set buffered datapath 


2$: 
CLRL Ri ; Return Success 
MOVZWL #SS$_NORMAL ,RO 
REQCOM 

; If subfunction modifier for device reset is set, do one here 

3$: BBC S*#I0$V_RESET ,R1,4$ ; Branch if not device reset 
BSBW XA_DEV_RESET ; Reset DR1i1-W 


; This must be a data transfer function - i.e. READ OR WRITE 
; Check to see if this is a zero length transfer. 
; If so, only set CSR FNCT bits and return STATUS from CSR 


4$: TSTW UCB$W_BCNT (R5) ; Is transfer count zero? 
BNEQ 10$ ; No, continue with data transfer 
BBC S*#I0$V_SETFNCT ,R1,6$ ; Set CSR FNCT specified? 
DEVICELOCK - 
LOCKADDR=UCB$L_DLCK(R5) ,- ; Lock device access 
SAVIPL=- (SP) , - ; Save current IPL 
PRESERVE=NO ; Don't preserve RO 


MOVW IRP$L_SEGVBN+2(R3) , XA_ODR(R4) 
; Store word in ODR 
MOVZWL XA_CSR(R4) ,RO 
BICW #<XA_CSR$M_FNCT ! XA_CSR$M_ERROR> , RO 
BISW IRP$L_SEGVBN (R3) , RO 
BISW #XA_CSR$M_ATTN, RO ; Force ATTN on to prevent lost interrupt 
MOVW =—- RO, XA_CSR(R4) 
BBC #XA$V_LINK , UCB$L_DEVDEPEND(R5) ,5$ ; Link mode? 


BICW3  #XA$K_FNCT2,RO, XA_CSR(R4) ; Make FNCT bit 2 a pulse 
5$: 
DEVICEUNLOCK - 
LOCKADDR=UCB$L_DLCK(R5),- ; Unlock device access 
NEWIPL=(SP) +, - ; Enable interrupts 
PRESERVE=NO 
6$: 
BSBW XA_REGISTER ; Fetch DR11i-W registers 
BLBS RO,7$ ; If error, then log it 
JSB G"ERL$DEVICERR ; Log a device error 
7$: JSB G* IOC$DIAGBUFILL ; Fill diagnostic buffer if specified 
MOVL UCB$W_XA_CSR(R5) , Ri ; Return CSR and EIR in Ri 


MOVZWL UCB$W_XA_ERROR(R5),RO ; Return status in RO 
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BISB #XA_CSR$M_IE,XA_CSR(R4) ; Enable device interrupts 


REQCOM ; Request done 

; Build CSR image in RO for later use in starting transfers 

10$: 

MOVZWL UCB$W_BCNT(R5) ,RO ; Fetch byte count 

DIVL3 #2,RO,UCB$L_XA_DPR(R5) ; Make byte count into word count 
; Set up UCB$W_CSRTMP used for loading CSR later 
MOVZWL XA_CSR(R4) ,RO 
BICW #°C<XA_CSR$M_FNCT>, RO 
BISW #XA_CSR$M_IE!XA_CSR$M_ATIN,RO ; Set Interrupt Enable and ATIN 
BBC S*#IO$V_SETFNCT,R1,20$ ; Set FNCT bits in CSR? . 
BICW #<XA_CSR$M_FNCT>, RO ; Yes, Clear previous FNCT bits 
BISB IRP$L_SEGVBN (R3) , RO ; OR in new value 

20$: BBC S*#IO$V_DIAGNOSTIC ,R1 , 23$ ; Check for maintenance function 
BISW #XA_CSR$M_MAINT, RO ; Set maintenance bit in CSR image 

; Is this a word mode or block mode request? 

23$ : MOVW RO, UCB$W_XA_CSRTMP(R5) ; Save CSR image in UCB 
BBC S*#IO0$V_WORD,R1,BLOCK_MODE ; Check if word or block mode 
BRW WORD_MODE ; Branch to handle word mode 


++ 


; BLOCK MODE -- Process a Block Mode (DMA) transfer request 


; FUNCTIONAL DESCRIPTION: 


: This routine takes the buffer address, buffer size, fucntion code, 

‘ and function modifier fields from the IRP. It calculates the UNIBUS 
: address, allocates the UBA map registers, loads the DR11-W device 

: registers and starts the request. 


; Set up UBA 
; Start transfer 


BLOCK_MODE: 
; If IO$M_CYCLE subfunction is specified, set CYCLE bit in CSR image 


BBC #IO$V_CYCLE ,R1,25$ ; Set CYCLE bit in CSR? 
BISW #XA_CSR$M_CYCLE, UCB$W_XA_CSRTMP(R5) ; If yes, OR into CSR image 


; Allocate UBA data path and map registers 


25$: 
REQDPR ; Request UBA data path 
REQMPR ; Request UBA map registers 
LOADUBA ; Load UBA map reqisters 


; Calculate the UNIBUS transfer address for the DR1i1-W from the UBA 
; map register address and byte offset. 
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MOVZWL UCB$W_BOFF(R5) ,R1 ; Byte offset in first page of xfer 
MOVL UCB$L_CRB(R5) ,R2 ; Address of CRB 
INSV CRB$L_INTD+VEC$W_MAPREG (R2) , #9,#9,R1 

; Insert page number 


EXTZV #16 ,#2,R1,R2 ; Extract bits 17:16 of bus address 
CMPB #DT$_DR11W, - ; If this is a DRii-W, 
UCB$B_DEVTYPE (R5) 

BEQL 100$ : then branch. 
MOVW R2,UCB$W_XA_BAETMP(R5) ; Save value of BAE prior to transfer 
CLRL R2 ; Clear XBA bits 

100$: ASHL #XA_CSR$V_XBA,R2,R2 ; Shift extended memory bits for CSR 
BISW #XA_CSR$M_GO,R2 ; Set "GO" bit into CSR image 


BISW R2,UCB$W_XA_CSRTMP(R5) ; Set into CSR image we are building 
BICW3  #<XA_CSR$M_GO!XA_CSR$M_CYCLE> , UCB$W_XA_CSRTMP(R5) ,RO 

; CSR image less "GO" and "CYCLE" 
BICW3 #XA$K_FNCT2,UCB$W_XA_CSRTMP(R5),R2 ; CSR image less FNCT bit 2 
MOVW R1,UCB$W_XA_BARTMP(R5) ; Save BAR for error logging 


; At this juncture: 

: RO = CSR image less "GO" and "CYCLE" 

: R1 = low 16 bits of transfer bus address 

; R2 = CSR image less FNCT bit 2 

: UCB$L_XA_DPR(R5) = transfer count in words 

; UCB$W_XA_CSRTMP(R5) = CSR image to start transfer with 


; Set DR11-W registers and start transfer 

; Note that read-modify-write cycles are NOT performed to the DR1ii-W CSR. 

; The CSR is always written directly into. This prevents inadvertently setting 
; the EIR select flag (writing bit 15) if error happens to become true. 


DEVICELOCK - 
LOCKADDR=UCB$L_DLCK(R5) ,- ; Lock device access 
SAVIPL=- (SP) ,- ; Save current IPL 
PRESERVE=NO ; Don't preserve RO 
SETIPL #31,- ; Raise to IPL POWER 


ENVIRON=UNIPROCESSOR 
MNEGW UCB$L_XA_DPR(R5) ,XA_WCR(R4) 
; Load negative of transfer count 


MOVW R1,XA_BAR(R4) ; Load low 16 bits of bus address 

CMPB #DT$_DR11W, - ; If this is a DR1i1-W, 
UCB$B_DEVTYPE(R5) 

BEQL 200$ : then branch. 

MOVW UCB$W_XA_BAETMP(R5),-  ; Load high bits of bus address 
XA_BAE(R4) 

200$: MOVW RO, XA_CSR(R4) ; Load CSR image less "GO" and "CYCLE" 

BBC #XA$V_LINK , UCB$L_DEVDEPEND(R5) ,26$ ; Link mode? 

MOVW R2,XA_CSR(R4) ; Yes, load CSR image less "FNCT" bit 2 

BRB 126$ ; Only if link mode in dev characteristics 


26$: 
MOVW UCB$W_XA_CSRTMP(R5) ,XA_CSR(R4) ; Move all bits to CSR 


; Wait for transfer complete interrupt, powerfail, or device timeout 


126$: 
WFIKPCH XA_TIME_OUT, IRP$L_MEDIA(R3) ; Wait for interrupt 


; Device has interrupted, FORK 
IOFORK ; FORK to lower IPL 5 


; Handle request completion, release UBA resources, check for errors 
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27$: 


300$: 
310$: 


28$: 


; Check 


30$: 


35$: 


37$: 
40$: 
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MOVZWL 
CLRW 
PURDPR 
BLBS 
MOVZWL 
INCB 
MOVL 
EXTZV 


MOVB 
EXTZV 
CMPB 


BEQL 
MOVZWL 
BRB 
EXTZV 
INSV 
CMPW 
BGTR 
MOVL 
CLRL 
DECL 
CMPV 


BGTR 
MOVL 
RELMPR 
RELDPR 


#SS$_NORMAL, - (SP) ; Assume success, store code on stack 

UCB$W_XA_DPRN(R5) ; Clear DPR number and DPR error flag 
; Purge UBA buffered data path 

RO, 27$ ; Branch if no datapath error 

#SS$_PARITY , (SP) ; Flag parity error on device 

UCB$W_XA_DPRN+1 (R5) ; Flag PDR error for log 

R1, UCB$L_XA_DPR(R5) ; Save data path register in UCB 

#VEC$V_DATAPATH, - Get Datapath register no. 

#VEC$S_DATAPATH, - For Error Log 

CRB$L_INTD+VEC$B _DATAPATH(R3) , RO 

RO, UCB$W_XA_DPRN (R5) ; Save for later in UCB 

#9 ,#7 , UCB$W_XA_BAR(R5) ,RO ; Low bits, final map register no. 

#DT$_DR11W, - ; If this is a DRi1-W, 

UCB$B_DEVTYPE (R5) 

300$ ; then branch. 

UCB$W_XA_BAE(R5) ,R1 ; Fetch high bits of map register no. 

310$ 

#4,#2,UCB$W_XA_CSR(R5),R1 ; Hi bits of map register no. 

R1,#7 ,#2,RO ; Entire map register number 

RO , #496 ; Is map register number in range? 

28$ ; No, forget it - compound error 

(R2) [RO] ,UCB$L_XA_FMPR(R5) ; Save map register contents 

UCB$L_XA_PMPR (R5) ; Assume no previous map register 

RO ; Was there a previous map register? 


#VEC$V_MAPREG , #VEC$S_MAPREG, - 

CRB$L_INTD+VEC$W_MAPREG(R3) , RO 

28$ ; No if gtr 

(R2) [RO] ,UCB$L_XA_FMPR(R5) ; Save previous map register contents 
; Release UBA resources 


for errors and return status 


TSTW 
BEQL 
MOVZWL 
BBC 
MOVZWL 
BSBW 
BLBS 


CMPW 
BNEQ 
CMPB 


BEQL 
BBS 


JSB 


BSBW 
JSB 
MOVL 
MULW3 
ADDW 
INSV 
MOVL 
BISB 
REQCOM 


UCB$W_XA_WCR(R5) ; All words transferred? 
30$ ; Yes 
#SS$_OPINCOMPL, (SP) ; No, flag operation not complete 


#XA_CSR$V_ERROR , UCB$W_XA_CSR(R5) ,35$ ; Branch on CSR error bit 
UCB$W_XA_ERROR(R5),(SP) ; Flag for controller/drive error status 


XA_DEV_RESET ; Reset DR11-W 
(SP) ,40$ ; Any errors after all this? 
(SP) , #SS$_OPINCOMPL ; Log the error, unless this is 
37$ ; a DRV11-WA running in link mode 
#DT$_DR11W, - ; and the operation is incomplete, 
UCB$B_DEVTYPE (R5) ; in which case it is an expected 
37$ ; error and not worth logging. 
#XA$V_LINK, - ets 
UCB$L_DEVDEPEND (R5) , 408 Si nat 
G*ERL$DEVICERR ; Log the error. 
DEL_ATTNAST ; Deliver outstanding ATTN AST's 
G* IOC$DIAGBUF ILL ; Fill diagnostic buffer 
(SP) +,RO ; Get final device status 


#2, UCB$W_XA_WCR(R5),R1 ; Calculate final transfer count 
UCB$W_BCNT(R5) ,R1 
R1,#16,#16,R0 | ; Insert into high byte of IOSB 
UCB$W_XA_CSR(R5) ,R1 ; Return CSR and EIR in IOSB 
#XA_CSR$M_IE,XA_CSR(R4) ; Enable interrupts 

; Finish request in exec 


Sample Driver for the DR11—W and DRV11—WA 


.DSABL LSB 
++ 
; WORD MODE -- Process word mode (interrupt per word) transfer 


; FUNCTIONAL DESCRIPTION: 


; Data is transferred one word at a time with an interrupt for each word. 
; The request is handled separately for a write (from memory to DR11-W 

; and a read (from DR11-W to memory). 

: For a write, data is fetched from memory, loaded into the ODR of the 

: DR1ii-W and the system waits for an interrupt. For a read, the system 

; waits for a DR11-W interrupt and the IDR is transferred into memory. 

; If the unsolicited interrupt flag is set, the first word is transferred 
; directly into memory withou waiting for an interrupt. 


-ENABL LSB 
WORD_MODE: 


; Dispatch to separate loops on READ or WRITE 


CMPB #I0$_READPBLK , R2 : Check for read function 
BNEQ 10$ ; Br if not, must be write function 
BRW 30$ ; Else, read 


t++ 


; WORD MODE WRITE -- Write (output) in word mode 


; FUNCTIONAL DESCRIPTION: 


; Transfer the requested number of words from user memory to 
; the DR11i-W ODR one word at a time, wait for interrupt for each 


; word. 
10$: 
BSBW MOVFRUSER ; Get two bytes from user buffer 
DEVICELOCK - 
LOCKADDR=UCB$L_DLCK(R5) ,- ; Lock device access 
SAVIPL=- (SP) , - ; Save current IPL 
PRESERVE=NO ; Don't preserve RO 
; Flag interrupt expected 
SETIPL #31,- ; Raise IPL to power 
ENVIRON=UNIPROCESSOR 
MOVW R1, XA_ODR(R4) ; Move data to DR1i1-W 
MOVW UCB$W_XA_CSRTMP(R5) ,XA_CSR(R4) ; Set DR11-W CSR 
BBC #XA$V_LINK, UCB$L_DEVDEPEND(R5) ,15$ ; Link mode? 
BICW3 #XA$K_FNCT2,UCB$W_XA_CSRTMP(R5) ,XA_CSR(R4) ; Clear interrupt FNCT bit 2 
; Only if link mode specified 
15$: 


; Wait for interrupt, powerfail, or device timeout 
WFIKPCH XA_TIME_OUTW, IRP$L_MEDIA(R3) 


; Check for errors, decrement transfer count, and loop until complete 
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IOFORK 
CMPB #DT$_DR11W, - 
UCB$B_DEVTYPE(R5) 
BEQL 17$ 
BBC #XA_CSR$V_ERROR, - 
UCB$W_XA_CSR(R5) , 20$ 
BRW 40$ 
17$: BITW #XA_EIR$M_NEX! - 
XA_EIR$M_MULTI! - 
XA_EIR$M_ACLO! - 
XA_EIR$M_PAR! - 
XA_EIR$M_DLT , UCB$W_XA_EIR(R5) 
BEQL 20$ 
BRW 40$ 
20$: DECW UCB$L_XA_DPR(R5) 
BNEQ 10$ 


DR11—W and DRV11—WA 


; Fork to lower IPL 
; Branch if this is a DR1i1-W 


; DRV11-WA - check ERROR bit in CSR. 
; Branch on success. 
; Branch on error. 


; Any errors? 
; No, continue 
; Yes, abort transfer. 
; All words transferred? 
; No, loop until finished. 


; Transfer is done, clear iterrupt expected flag and FORK 


; All words read or written in WORD MODE. 


RETURN_STATUS : 


JSB G* IOC$DIAGBUFILL 
BSBW DEL_ATTNAST 
MOVZWL #SS$_NORMAL,RO 

22$ : MULW3 #2,UCB$L_XA_DPR(R5) ,R1 
SUBW3 R1,UCB$W_BCNT(R5) ,R1 
INSV Ri, #16, #16, RO 
MOVL UCB$W_XA_CSR(R5) ,R1 
BISB #XA_CSR$M_IE, XA_CSR(R4) 
REQCOM 


++ 


Finish 1/0. 


; Fill diagnostic buffer if present 
; Deliver outstanding ATTN AST's 

; Complete success status 

; Calculate actual bytes xferred 

; From requested number of bytes 

; And place in high word of RO 

; Return CSR and EIR status 

; Enable device interrupts 

; Finish request in exec 


; WORD MODE READ -- Read (input) in word mode 
; FUNCTIONAL DESCRIPTION: 


; Transfer the requested number of words from the DR11-W IDR into 

; user memory one word at a time, wait for interrupt for each word. 
; If the unexpected (unsolicited) interrupt bit is set, transfer the 
: first (last received) word to memory without waiting for an 

} interrupt. 


DEVICELOCK - 
LOCKADDR=UCB$L_DLCK(R5) ,- ; Lock device access 
SAVIPL=- (SP) , - ; Save current IPL 
PRESERVE=NO ; Don't preserve RO 


; If an unexpected (unsolicited) interrupt has occurred, assume it 
; is for this READ request and return value to user buffer without 
; waiting for an interrupt. 


BBCC #UCB$V_UNEXPT, - 
UCB$W_DEVSTS(R5) ,32$ 


DEVICEUNLOCK - 
LOCKADDR=UCB$L_DLCK(R5) ,- ; Unlock device access 
NEWIPL=(SP) +, - ; Enable interrupts 
PRESERVE=NO 

37$ ; 


; Branch if no unexpected interrupt 


BRB continue 


32$: 
SETIPL #IPL$_POWER, - 
ENVIRON=UNIPROCESSOR 


35$: 
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; Wait for interrupt, powerfail, or device time-out 
WFIKPCH XA_TIME_OUTW, IRP$L_MEDIA(R3) 


; Check for errors, decrement transfer count and loop until done 


IOFORK ; Fork to lower IPL 
37$: 

CMPB #DT$_DR11W, - ; Branch if this is a DR11-W 
UCB$B_DEVTYPE (R5) 

BEQL 1037$ 

BBC #XA_CSR$V_ERROR, - ; DRV11-WA - check ERROR bit in CSR. 
UCB$W_XA_CSR(R5) ,1038$ ; Branch on success. 

BRW 40$ ; Branch on error. 


1037$: BITW #XA_EIR$M_NEX! - 
XA_EIR$M_MULTI! - 
XA_EIR$M_ACLO! - 
XA_EIR$M_PAR! - 
XA_EIR$M_DLT,UCB$W_XA_EIR(R5) ; Any errors? 
BNEQ 40$ ; Yes, abort transfer. 
1038$: BSBW MOVTOUSER ; Store two bytes into user buffer 


; Send interrupt back to sender. Acknowledge we got last word. 


DEVICELOCK - 
LOCKADDR=UCB$L_DLCK(R5) ,- ; Lock device access 
SAVIPL=- (SP) , - ; Save current IPL 
PRESERVE=NO ; Don't preserve RO 


MOVW UCB$W_XA_CSRTMP(R5) , XA_CSR(R4) 
BBC #XA$V_LINK , UCB$L_DEVDEPEND(R5) ,38$ ; Link mode? 
BICW3 #XA$K_FNCT2,UCB$W_XA_CSRTMP(R5) ,XA_CSR(R4) ; Yes, clear FNCT 2 


38$: 
DECW UCB$L_XA_DPR (R5) ; Decrement transfer count 
BNEQ 35$ ; Loop until all words transferred 
DEVICEUNLOCK - 
LOCKADDR=UCB$L_DLCK(R5),- ; Unlock device access 
NEWIPL=(SP) +, - ; Enable interrupts 
PRESERVE=NO 
BRW RETURN_STATUS ; Finish request in common code 


; Error detected in word mode transfer 


A40$: 
BSBW DEL_ATTNAST ; Deliver ATTN AST's 
BSBW XA_DEV_RESET ; Error, reset DR11-W 
JSB G* IOC$DIAGBUF ILL ; Fill diagnostic buffer if present 
JSB G°ERL$DEVICERR ; Log device error 
MOVZWL UCB$W_XA_ERROR(R5) ,RO ; Set controller/drive status in RO 
BRW 22$ 


F—-17 


Sample Driver for the DR11—W and DRV11—WA 


.DSABL LSB 


; MOVFRUSER - Routine to fetch two bytes from user buffer. 


; INPUTS: 
; R5 = UCB address 


; OUTPUTS: 


; Ri = Two bytes of data from user's buffer 
: Buffer descriptor in UCB is updated. 


.ENABL LSB 
MOVFRUSER : 

MOVAL -(SP),R1 

MOVZBL #2,R2 


JSB G* IOC$MOVFRUSER 
MOVL (SP)+,Ri 
BRB 20$ 


Address of temporary stack loc 
Fetch two bytes 

Call exec routine to do the deed 
Retrieve the bytes 

Update UCB buffer pointers 


; MOVTOUSER - Routine to store two bytes into user's buffer. 


; INPUTS: 


: R5 = UCB address 


‘ UCB$W_XA_IDR(R5) = Location where two bytes are saved 


; OUTPUTS: 


i Two bytes are stored in user buffer and buffer descriptor in 


; UCB is updated. 


MOVTOUSER : 
MOVAB UCB$W_XA_IDR(R5) ,R1 
MOVZBL #2,R2 


JSB G* IOC$MOVTOUSER : 
20$: ; 

ADDW #2, UCB$W_BOFF (R5) : 

BICW #°C<*X01FF>, UCB$W_BOFF (R5) 

BNEQ 30$ : 

ADDL #4, UCB$L_SVAPTE(R5) : 
30$: 

RSB 

.DSABL LSB 

. PAGE 


.SBTTL DR11-W DEVICE TIMEOUT 
++ 
; DRi1-W device TIME-OUT 


; Address of internal buffer 


; Call exec 
; Update buffer pointers in UCB 
; Add two to buffer descriptor 


; Modulo the page size 


; If NEQ, no page boundary crossed 
; Point to next page 


; If a DMA transfer was in progress, release UBA resources. 
; For DMA or WORD mode, deliver ATTN ASTs, log a device timeout error, 


; and do a hard reset on the controller. 


; Clear DR11-W CSR 
; Return error status 


; Power failure will appear as a device timeout 


.ENABL LSB 
XA_TIME_OUT: 
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, 


; Timeout for DMA transfer 


IOFORK 
PURDPR 
RELMPR 
RELDPR 
BRB 


XA_TIME_OUTW: 


IOFORK 
10$: MOVL 
MOVL 
BSBW 
JSB 
JSB 
BSBW 
BSBW 
MOVZWL 
BBC 


MOVZWL 
20$: CLRL 
BICW 


BICW 


REQCOM 
. DSABL 
. PAGE 


.OBTTL 
t+ 


; XA_INTERRUPT 


Sample Driver for the DR11—W and DRV11—WA 


; Fork to complete request 
; Purge buffered data path in UBA 
; Release UBA map registers 
; Release UBA data path 
10$ ; continue 


; Timeout for WORD mode transfer 


; Fork to complete operations 


UCB$L_CRB(R5) ,R4 ; Fetch address of CSR 
@CRB$L_INTD+VEC$L_IDB(R4) ,R4 

XA_REGISTER ; Read DR11-W registers 
G* IOC$DIAGBUF ILL ; Fill diagnostic buffer 
G"ERL$DEVICTMO ; Log device time out 
DEL_ATTNAST ; And deliver the ASTs 
XA_DEV_RESET ; Reset controller 
#SS$_TIMEOUT, RO ; Assume error status 
#UCB$V_CANCEL, - 

UCB$W_STS(R5) , 20$ ; Branch if not cancel 
#SS$_CANCEL, RO ; Set status 

R1 


#UCB$M_ATTNAST ! UCB$M_UNEXPT , UCB$W_DEVSTS (R5) 
; Clear unwanted flags. 
#<UCB$M_TIM! UCB$M_INT! UCB$M_TIMOUT ! UCB$M_CANCEL! UCB$M_POWER> , - 
UCB$W_STS (R5) ; Clear unit status flags 
; Complete I/O in exec 
LSB 


XA_INTERRUPT, Interrupt service routine for DR11-W 


, Handles interrupts generated by DR1i1-W 


; Functional description: 


: This routine is entered whenever an interrupt is generated 


; by the 
: If not 


DRii-W. It checks that an interrupt was expected. 


, it sets the unexpected (unsolicited) interrupt flag. 


: All device registers are read and stored into the UCB. 

; If an interrupt was expected, it calls the driver back at its Wait 
: For Interrupt point. 

: Deliver ATTN ASTs if unexpected interrupt. 


; Inputs: 


; 00(SP) 
: 04 (SP) 
; 08 (SP) 
' 12(SP) 
i 16 (SP) 
: 20(SP) 
; 24 (SP) 
: 28 (SP) 
i 32(SP) 


; Outputs: 


Pointer to address of the device IDB 
saved RO 

saved R1 

saved R2 

saved R3 

saved R4 

saved R5 

saved PSL 

= saved PC 


; The driver is called at its Wait For Interrupt point if an 
; interrupt was expected. 
i The current values of the DR11-W CSRs are stored in the UCB. 


, 


XA_INTERRUPT : 
MOVL 


; Interrupt service for DR11-W 
@(SP)+,R4 ; Address of IDB and pop SP 
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MOVQ (R4) ,R4 ; CSR and UCB address from IDB 
DEVICELOCK - 
LOCKADDR=UCB$L_DLCK(R5) ,- ; Lock device access 
CONDITION=NOSETIPL, - ; Don't change IPL 
PRESERVE=NO ; Don't preserve RO 


; Read the DR11-W device registers (WCR, BAR, CSR, EIR, IDR) and store 
; into UCB. 


BSBW XA_REGISTER ; Read device registers 


; Check to see if device transfer request active or not 
; If so, call driver back at Wait for Interrupt point and 
; Clear unexpected interrupt flag. 


20$: BBCC #UCB$V_INT ,UCB$W_STS(R5) , 25$ 
; If clear, no interrupt expected 


; Interrupt expected, clear unexpected interrupt flag and call driver 
; back. 


BICW #UCB$M_UNEXPT , UCB$W_DEVSTS (R5) 
; Clear unexpected interrupt flag 


MOVL UCB$L_FR3(R5) ,R3 ; Restore driver's R3 
JSB @UCB$L_FPC(R5) ; Call driver back 
BRB 30$ 


; Deliver ATTN ASTs if no interrupt expected and set unexpected 
; interrupt flag. 


25$: BBSC #UCB$V_IGNORE_UNEXPT,- ; Ignore spurious interrupt - 
UCB$W_DEVSTS(R5),24$ ; (DRV11-WA only.) 
BISW #UCB$M_UNEXPT , UCB$W_DEVSTS(R5) ; Set unexpected interrupt flag 
BSBW DEL_ATTNAST ; Deliver ATTN ASTs 
BISB #XA_CSR$M_IE,XA_CSR(R4) ; Enable device interrupts 
BRB 30$ 


; Restore registers and return from interrupt 


24$ : NOP ; allow a breakpoint here (spurious interrupt) 
30$: DEVICEUNLOCK - 
LOCKADDR=UCB$L_DLCK(R5),- ; Unlock device access 
PRESERVE=NO0 ; Don't preserve RO 
POPR #°M<RO,R1,R2,R3,R4,R5> ; Restore registers 
REI ; Return from interrupt 
. PAGE 


.SBTTL XA_REGISTER - Handle DRi1i-W CSR transfers 


++ 


; XA_LREGISTER - Routine to handle DR11-W register transfers 
; INPUTS: 

: R4 - DR11-W CSR address 

; RS - UCB address of unit 


; OUTPUTS: 


; CSR, EIR, WCR, BAR, BAE, IDR, and status are read and stored into UCB. 
i The DRi1-W is placed in its initial state with interrupts enabled. 

; RO - .true. if no hard error 

: .false. if hard error (cannot clear ATTN) 


; If the CSR ERROR bit is set and the associated condition can be cleared, then 
; the error is transient and recoverable. The status returned is SS$_DRVERR. 

; If the CSR ERROR bit is set and cannot be cleared by clearing the CSR, then 

; this is a hard error and cannot be recovered. The returned status is 
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; SS$_CTRLERR. 
; RO,Ri - destroyed, all other registers preserved. 


XA_REGISTER: 


MOVZWL #SS$_NORMAL ,RO ; Assume success 
MOVZWL XA_CSR(R4) ,R1i ; Read CSR 
MOVW R1,UCB$W_XA_CSR(R5) ; Save CSR in UCB 
BBC #XA_CSR$V_ERROR,R1,55$ ; Branch if no error 
MOVZWL #SS$_DRVERR,RO ; Assume "drive" error 
55$: BICW #°C<XA_CSR$M_FNCT>,R1 ; Clear all uninteresting bits for later 
CMPB #DT$_XA_DRV11WA, - ; If this is a DRV11-WA, 
UCB$B_DEVTYPE(R5) ; 
BEQL 57$ : then branch. 


BISB #<XA_CSR$M_ERROR/256>,XA_CSR+1(R4) ; Set EIR flag 
MOVW XA_EIR(R4) ,UCB$W_XA_EIR(R5) ; Save EIR in UCB 


BRB 59$ 
57$: BISW #XA_CSR$M_IE,R1 ; On the DRV11-WA, if the IE bit makes 
; a O->1 transition while READY=1, a 
; Spurious interrupt is generated. 
; Therefore, we leave IE high at all 
; times. : 
59$: MOVW R1,XA_CSR(R4) ; Clear EIR flag and errors 
MOVW XA_CSR(R4) ,R1 ; Read CSR back 
BBC #XA_CSR$V_ATTN ,R1,60$ ; If attention still set, hard error 
MOVZWL #SS$_CTRLERR, RO ; Flag hard controller error 


60$: MOVW XA_IDR(R4) , UCB$W_XA_IDR(R5) ; Save IDR in UCB 
MOVW XA_BAR(R4) , UCB$W_XA_BAR (R5) 


CMPB #DT$_DR11W, - ; If this is a DR11-W, 
UCB$B_DEVTYPE(R5) ; 
BEQL 70$ : then branch. 


MOVW XA_BAE(R4) , UCB$W_XA_BAE(R5) ; Save BAE in UCB 
70$: MOVW XA_WCR(R4) , UCB$W_XA_WCR(R5) 

MOVW RO, UCB$W_XA_ERROR (R5) ; Save status in UCB 

RSB 


.SBTTL XA_CANCEL, Cancel I/0 routine 
++ 
; XA_CANCEL, Cancels an I/O operation in progress 


; Functional description: 


; Flushes Attention AST queue for the user. 

: If transfer in progress, do a device reset to DR11-W and finish the 
; request. 

: Clear interrupt expected flag. 


; Inputs: 

; R2 = negated value of channel index 

; R3 = address of current IRP 

: R4 = address of the PCB requesting the cancel 

: RS = address of the device's UCB 

; Outputs: 

XA_CANCEL: ; Cancel 1/0 
BBCC #UCB$V_ATTNAST, - 


UCB$W_DEVSTS(R5) , 20$ ; ATTN AST enabled? 
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; Finish all ATTN ASTs for this process. 
PUSHR #°M<R2,R6,R7> 


MOVL R2,R6 ; Set up channel number 
MOVAB UCBS$L_XA_ATTN(R5) ,R7 ; Address of listhead 
JSB G* COM$FLUSHATTNS ; Flush ATTN ASTs for process 


POPR #°M<R2,R6,R7> 


; Check to see if a data transfer request is in progress 
; for this process on this channel 


20$ : 

DEVICELOCK - 
LOCKADDR=UCB$L_DLCK(R5) ,- ; Lock device access 
SAVIPL=- (SP) , - ; Save current IPL 
PRESERVE=NO ; Don't preserve RO 

BBC #UCB$V_INT, - ; br if I/0 not in progress 
UCB$W_STS(R5) , 30$ 

JSB G* IOC$CANCELIO ; Check if transfer going 

BBC #UCB$V_CANCEL, - 
UCB$W_STS(R5) ,30$ ; Branch if not for this guy 


; Force timeout 
CLRL UCB$L_DUETIM(R5) ; clear timer 
BISW #UCB$M_TIM, UCB$W_STS(R5) ; set timed bit 
BICW #UCB$M_TIMOUT, - 


UCB$W_STS(R5) ; Clear timed out 
30$: 
DEVICEUNLOCK - 
LOCKADDR=UCB$L_DLCK(R5) ,- ; Unlock device access 
NEWIPL=(SP) +,- ; Enable interrupts 
PRESERVE=NO 


RSB ; Return 


. PAGE 
.SBITL DEL_ATTNAST, Deliver ATTN ASTs 


++ 


, 


; DEL_ATTNAST, Deliver all outstanding ATIN ASTs 

; Functional description: 

; This routine is used by the DR11-W driver to deliver all of the 

: outstanding attention ASTs. It is copied from COM$DELATTNAST in 

; the exec. In addition, it places the saved value of the DR11-W CSR 
; and Input Data Buffer Register in the AST parameter. 

; Inputs: 

; RS = UCB of DR1i1-W unit 

; Outputs: 


: RO,R1,R2 Destroyed 
: R3,R4,R5 Preserved 


DEL_ATTNAST: 


DEVICELOCK - 
LOCKADDR=UCB$L_DLCK(R5) ,- ; Lock device access 
SAVIPL=- (SP) ,- ; Save current IPL 
PRESERVE=NO ; Don't preserve RO 


BBCC #UCB$V_ATTNAST , UCB$W_DEVSTS(R5) , 30$ 
; Any ATTN ASTs expected? 
PUSHR #°M<R3,R4,R5> ; Save R3,R4,R5 
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10$: MOVL 
MOVAB 
MOVL 
BEQL 
BICW 
MOVL 
MOVW 


MOVW 


PUSHAB 
FORK 


Sample Driver for the DR11—W and DRV11—WA 


8(SP) ,R1 ; Get address of UCB 

UCB$L_XA_ATTN(R1) ,R2 ; Address of ATTN AST listhead 

(R2) ,R5 ; Address of next entry on list 

20$ ; No next entry, end of loop 
#UCB$M_UNEXPT, UCB$W_DEVSTS(R1i) ; Clear unexpected interrupt flag 
(R5) , (R2) ; Close list 


UCB$W_XA_IDR(R1) , ACB$L_KAST+6(R5) 

; Store IDR in AST parameter 
UCB$W_XA_CSR(R1) , ACB$L_KAST+4 (R5) 

; Store CSR in AST parameter 
B~10$ ; Set return address for FORK 

; FORK for this AST 


; AST fork procedure 


MOVQ 


MOVB 
MOVL 
CLRL 
MOVZBL 
JMP 


20$: POPR 


ACB$L_KAST(R5) , ACB$L_AST(R5) 

; Rearrange entries 
ACB$L_KAST+8(R5) , ACB$B_RMOD (R5) 
ACB$L_KAST+12(R5) , ACB$L_PID(R5) 

ACB$L_KAST (R5) 


30$: DEVICEUNLOCK - 


RSB 


. PAGE 
.SBTTL 


t++ 


#PRI$_IOCOM,R2 ; Set up priority increment 
G*SCH$QAST ; Queue the AST 
#°M<R3,R4,R5> ; Restore registers 
LOCKADDR=UCB$L_DLCK(R5) ,- ; Unlock device access 
NEWIPL=(SP) +,- ; Enable interrupts 


PRESERVE=NO 
; Return 


XA_REGDUMP - DR1i1i-W register dump routine 


; XA_REGDUMP - DR11-W Register dump routine. 


; This routine is called to save the controller registers in a specified 
; buffer. It is called from the device error logging routine and from the 
; diagnostic buffer fill routine. 


; Inputs: 


: RO - Address of register save buffer 


: R4 - Address of Control and Status Register 
: R5 - Address of UCB 


; Outputs: 


; The controller registers are saved in the specified buffer. 


CSRTMP - The last command written to the DR11-W CSR by 
by the driver. 

BARTMP - The last value written into the DR1i1-W BAR by 
the driver during a block mode transfer. 

CSR - The CSR image at the last interrupt 

EIR - The EIR image at the last interrupt 

IDR - The IDR image at the last interrupt 

BAR - The BAR image at the last interrupt 

WCR - Word count register 

ERROR - The system status at request completion 

PDRN - UBA Datapath Register number 

DPR - The contents of the UBA Data Path register 

FMPR - The contents of the last UBA Map register 

PMRP - The contents of the previous UBA Map register 

DPRF - Flag for purge datapath error 
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‘ 0 = no purger datapath error 
1 = parity error when datapath was purged 
; BAETMP - The last value written to the BAE by the 
; driver during a block mode transfer (DRV11-WA only) 
; BAE - The BAE image at the last interrupt (DRV11-WA only) 


; Note that the values stored are from the last completed transfer 


: operation. If a zero transfer count is specified, then the 
: ' values are from the last operation with a non-zero transfer count. 


XA_REGDUMP : 


MOVZBL #15, (RO)+ ; 15 registers are stored. 
MOVAB UCB$W_XA_CSRTMP(R5),R1 ; Get address of saved register images 
MOVZBL_ #8,R2 ; Return 8 registers here 

10$: MOVZWL (R1)+,(RO)+ 
SOBGTR R2,10$ ; Move them all 
MOVZBL UCB$W_XA_DPRN(R5),(RO)+ ; Save Datapath Register number 
MOVZBL #3,R2 ; And 3 more here 

20$ : MOVL (R1)+, (RO) + ; Move UBA register contents 


SOBGTR R2,20$ 

MOVZBL UCB$W_XA_DPRN+1(R5),(RO)+ ; Save Datapath Parity Error Flag 
MOVZWL UCB$W_XA_BAETMP(R5),(RO)+ ; Save BAE stored prior to xfer 
MOVZWL UCB$W_XA_BAE(R5),(RO)+ ; Save BAE store following xfer 
RSB 


. PAGE 
.SBITL XA_DEV_RESET - Device reset DR11-W 
++ 


; XA_DEV_RESET - DR1i1-W Device reset routine 


; This routine raises IPL to device IPL, performs a device reset to 
; the required controller, and reenables device interrupts. 


; Must be called at or below device IPL to prevent a confict in 
; acquiring the device_spinlock. 


; Inputs: 


; R4 - Address of Control and Status Register 
; R5 - Address of UCB 


; Outputs: 


: Controller is reset, controller interrupts are enabled 


XA_DEV_RESET : 


PUSHR #°M<RO,R1,R2> ; Save some registers 
DEVICELOCK - . 
LOCKADDR=UCB$L_DLCK(R5) ,- ; Lock device access 
SAVIPL=- (SP) , - ; Save current IPL 
PRESERVE=NO ; Don't preserve RO 
BSBB XA_DEV_HWRESET 
DEVICEUNLOCK - 
LOCKADDR=UCB$L_DLCK(R5),- ; Unlock device access 
NEWIPL=(SP)+, - ; Enable interrupts 
PRESERVE=NO 
POPR #°M<RO,R1 ,R2> ; Restore registers 
RSB 
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XA_DEV_HWRESET : 


CMPB #DT$_DR1iiW, - ; If this is a DRii-W, 
UCB$B_DEVTYPE(R5) ; 
BEQL 20$ woe then branch. 


MOVW #XA_CSR$M_IE,XA_CSR(R4) ; Clear all writable bits but IE. 
BITB #XA_CSR$M_RDY,XA_CSR(R4); If not READY then no xfer in progress, 


BNEQ 40$ ; So no need to reset device 

MNEGW #1,XA_WCR(R4) ; Tell it only i byte left to xfer 

MOVB #XA_CSR$M_CYCLE/256,-  ; and complete the transfer. 
XA_CSR+1 (R4) | 

BRB 30$ 


20$: MOVB #<XA_CSR$M_MAINT/256>, XA_CSR+1 (R4) 
CLRB XA_CSR+14 (R4) 


; *** Must delay here depending on reset interval 


30$: TIMEDWAIT TIME=#XA_RESET_DELAY ; No. of 10-micro-sec intervals to wait 
MOVB #XA_CSR$M_IE,XA_CSR(R4) ; Reenable device interrupts 
40$: RSB 
XA_END: ; End of driver label 
.END . 


F-25 
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Several features of VMS Version 5.0 have some impact on the execution 
of existing non-DIGITAL-supplied kernel-mode code, most notably device 
drivers. This chapter describes those changes DIGITAL requires or 
recommends in an existing non-DIGITAL-supplied device driver. It also 
provides a brief explanation of key VMS concepts that are integral to an 
understanding of the operation of privileged code under VMS Version 5.0. 


G.1 Uniprocessor and Multiprocessor Device Drivers 





One of the most significant components of VMS Version 5.0 is its support of 
a symmetric multiprocessing environment for certain VAX systems, including 
the VAX 8300/8350, VAX 8800/8830/8840, and VAX 6200 series. The 
multiprocessing environment provided by earlier versions of VMS was 
asymmetric in nature. Because only the primary processor could execute 
kernel-mode code, kernel-mode code, including device drivers, effectively ran 
in a uniprocessing environment and did not need to undertake any special 
actions due to the multiprocessing nature of the system. 


In the symmetric multiprocessing environment supported by VMS Version 
5.0, however, all processors in the system can execute kernel-mode code. 
Consequently, privileged code must take steps to ensure that its execution 
and use of memory are synchronized with kernel-mode code that may be 
executing concurrently on another processor. Such code must maintain 
two dimensions of synchronization: raising to the appropriate IPL for a 
certain transaction, while securing the proper spin lock for the object of that 
transaction. 


For privileged code executing within a VMS uniprocessing environment 
VMS Version 5.0 transparently forgoes the second of these requirements. 
That is, on a VAX uniprocessor, or in a VMS multiprocessor system wherein 
multiprocessing is not enabled, privileged code may securely execute by 
adhering to the IPL synchronization method alone. 


To support both uniprocessor and multiprocessor environments in the most 
efficient and secure way possible, VMS Version 5.0 incorporates special 
logic in the System Generation Utility (SYSGEN), the device driver loading 
mechanism, and several synchronization macros. This code enables VMS to 
discern the environment in which it is executing and, most importantly, to 
take steps to prohibit a privileged code thread from executing without proper 
synchronization in a multiprocessing environment. 


As discussed in Section G.3, non-DIGITAL-supplied device drivers must be 
altered to execute correctly in a VMS symmetric multiprocessing environment. 
The modifications discussed in Section G.3 are not required for a device 
driver that will be loaded and executed only on a VMS uniprocessor 

system. However, the same macros, routines, and field names used in 

a multiprocessing environment are accepted by VMS in a uniprocessing 
environment. Furthermore, the spin lock synchronization macros. and 
routines are specially designed to execute a streamlined code that obtains 
IPL synchronization alone in such an environment. DIGITAL recommends 
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that any driver that may execute in a multiprocessing environment be updated 
accordingly. 


The remainder of this section identifies the activities of the 
MULTIPROCESSING system parameter, VMS driver loading mechanisms, 
and the VMS synchronization macros in creating a multiprocessing or 
uniprocessing environment and enforcing the appropriate synchronization. 


G.1.1 MULTIPROCESSING System Parameter 
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Every VMS system is initially booted as a single processor, regardless 

of its hardware configuration. The setting of the MULTIPROCESSING 
system parameter for the first processor in the system to boot (called the 
primary processor in a multiprocessing environment) determines which 
synchronization image the secondary bootstrap program (SYSBOOT) loads 
into memory as part of the operating system. Table G-1 describes the 
contents of the three possible synchronization images. 


Table G—1_ VMS Synchronization Images 


Image Results 


Uniprocessing Synchronization is accomplished by elevating IPL. Spin 
lock acquisition routines only achieve IPL synchronization. 


Full-checking Synchronization is accomplished by both elevating IPL 
and obtaining an appropriate spin lock. Spin lock 
acquisition routines perform both of these tasks. Spin 
lock acquisition routines also perform spin lock rank 
checking and verify the spin lock synchronization IPL, 
issuing appropriate bugchecks if they discover violations 
of synchronization rules. Spin lock acquisition routines 
maintain various debugging aids and performance analysis 
aids (such as the longwords in the spin lock data structure 
containing the PCs of the most recent acquisitions and 
releases of the spin lock and the set of counters in the 
per-CPU database structure (CPU)). (See Section G.3.7 for 
additional description of full-checking synchronization.) 


Streamlined Synchronization is accomplished by both elevating IPL and 
obtaining an appropriate spin lock. Spin lock acquisition 
routines do not perform checking and do not record the 
PCs of the spin lock acquisitions and releases. 


Table G-2 lists the possible settings of the MULTIPROCESSING system 
parameter. 
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Table G-2 Settings of MULTIPROCESSING System Parameter 
Value Result 


0 Loads uniprocessing synchronization image for any hardware 
~ configuration 


1 Loads full-checking synchronization image and sets multiprocessing- 
enabled bit (SMP$V_ENABLED in SMP$GL_FLAGS) if the hardware 
configuration is capable of multiprocessing and two or more processors 
are available; otherwise, loads unuprocessing synchronization image. 
This is the default value. 


2 Loads full-checking synchronization image and sets multiprocessing- 
enabled bit regardless of the hardware configuration. 


3 Loads streamlined synchronization image and sets multiprocessing- 
enabled bit if the hardware configuration is capable of multiprocessing 
and two or more processors are available; otherwise, loads 
uniprocessing synchronization image. 


G.1.2 Device Driver Loading 


In a VMS multiprocessing environment, the presence of a device driver that 
does not adhere to multiprocessing synchronization conventions can be fatal 
to proper system functions. VMS Version 5.0 takes steps to either prohibit the 
enabling of multiprocessing in a VAX system that has such a driver present 
or prevent the loading of such a driver if multiprocessing has already been 
enabled. 


To accomplish this, the VMS driver-loading routine assumes that any driver 
that can run in a VMS multiprocessing environment uses the spin lock 
synchronization macros and loads the appropriate I/O database fields. (See 
Section G.3 for information on how to produce a driver that can execute in a 
VMS multiprocessing environment.) Use of the spin lock synchronization 
macros causes VMS to set the SMP-modified bit in the DPT (DPT$V_ 
SMPMOD in DPT$L_FLAGS). 


If multiprocessing has not been enabled on the system, the driver loading 
mechanism checks the SMP-modified bit in the DPT and takes either of the 
following actions: 


e If the SMP-modified bit is set, the driver loading mechanism loads the 
driver and calls its controller and unit initialization routines, as discussed 
in Chapter 15. 


¢ If the SMP-modified bit is not set, the driver loading mechanism sets 
the unmodified-driver bit (GMP$V_UNMOD_DRIVER) in SMP$GL_ 
FLAGS, thus prohibiting the subsequent enabling of multiprocessing 
on the system. It then loads the driver and calls its controller and unit 
initialization routines, as described in Chapter 15. If such a driver has 
been successfully loaded into a VMS system, you cannot subsequently 
enable multiprocessing. 
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If multiprocessing is currently enabled on the system, the driver loading 
mechanism checks the SMP-modified bit in the DPT and takes either of the 
following actions: 


e If the SMP-modified bit is set, the driver loading mechanism loads the 
driver and calls its controller and unit initialization routines, as discussed 
in Chapter 15. 


e If the SMP-modified bit is not set, the driver loading mechanism does 
not load the driver, returning the error status SS$_NONSMPDRV to its 
caller. 


G.1.3. VMS Synchronization Macros 


To support the spin lock synchronization required in VMS multiprocessor 
systems, VMS Version 5.0 adds the DEVICELOCK/DEVICEUNLOCK, 
FORKLOCK/FORKUNLOCK, and LOCK/UNLOCK macros to the existing 
SETIPL and DSBINT/ENBINT macros. As discussed in Section G.3, the 
SETIPL and DSBINT/ENBINT macros must not be used to synchronize 
systemwide activities in a VMS multiprocessing environment. However, 
the DEVICELOCK/DEVICEUNLOCK, FORKLOCK/FORKUNLOCK, and 
LOCK/UNLOCK macros are designed to operate appropriately in either a 
multiprocessing or uniprocessing environment. According to the value of the 
multiprocessing-enabled bit (GMP$V_ENABLED) in SMP$GL_FLAGS, the 
run-time code produced by these macros behaves as follows: 


e If multiprocessing has not been enabled in the system, these macros 
only raise or lower IPL to the IPL required to synchronize access to the 
specified system resource. 


¢ If multiprocessing has bee: enabled in the system, these macros call the 
appropriate spin lock synchronization routine, which acquires or releases 
the spin lock corresponding to the system resource, raising or lowering 
IPL as required. 


The setting of the MULTIPROCESSING system parameter controls the 
disposition of the multiprocessing-enabled bit, as discussed in Section G.1. 1. 
Appendix B describes the VMS synchronization macros in full. 





G.2 Changes Required of All Existing Drivers Under VMS Version 5.0 


Most changes in VMS Version 5.0 are transparent to existing non-DIGITAL- 
supplied drivers and can be accommodated in the driver image by simply 
reassembling and relinking the driver. However, there are several required— 
and some recommended—changes that the writers and maintainers of these 
drivers should make before attempting these tasks. This section describes 
these modifications. 


In addition, if a non-DIGITAL-supplied driver is to be loaded and run in 

a VMS symmetric multiprocessing system, it is critical that it be adapted 
according to the guidelines discussed in Section G.3. Failure to adapt such 
drivers to use multiprocessing synchronization mechanisms may result in 
either a failure to load the driver or the inability to enable multiprocessing on 
the system. 
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G.2.1 Specifying the Address of the Driver's Interrupt Service Routine 


in the DPT 


In order to provide an optional method of servicing MicroVAX 3600-series 
or MicroVAX II Q22-bus device interrupts at the IPLs at which they are 
requested, VMS Version 5.0 defines several new symbolic offsets in the 
interrupt dispatch vector (VEC) portion of the channel request block (CRB). 


One of these symbolic offsets is significant to all device drivers. Prior to VMS 
Version 5.0, device drivers initialized the location in the vector containing the 
address of the driver’s interrupt service routine by referring explicitly to its 
location (CRB$L_INTD+4). With VMS Version 5.0, DIGITAL recommends 
that all device drivers refer to this location using the eyEipone offset CRB$L_ 
INTD+VEC$L_ISR, as follows: 


Old: DPT_STORE CRB,CRB$L_INTD+4,D,LP$INT_SERV_RTN 
New: DPT_STORE CRB,CRB$L_INTD+VEC$L_ISR,D,LPSINT_SERV_RTN 


To use the new symbols, you must include the $CRBDEF and $VECDEF 
structure definition macros in the driver. All structure definition macros can 
be found in SYS$LIBRARY:LIB.MLB. 


G.2.2 Checking, Debiting, and Crediting a Process’s Byte Count Quota 


VMS Version 5.0 replaces the routines EXE$SBUFFRQUOTA and 
EXE$BUFQUOPRC with a set of eight new routines that manipulate a job’s 
byte count quota and byte limit, optionally allocating a nonpaged pool buffer 
of the requested size. To ensure proper synchronization, programs should use 
these routines and avoid any direct manipulation of the nonpaged pool quota 
fields JIB$L_BYTCNT and JIB$L_BYTLM). 


Among the new routines are the following: 


Routine Function 

EXE$CREDIT_BY TCNT Returns credit to a job’ s byte count 
quota . 

EXESCREDIT_BYTCNT_BYTLM Returns credit to a job’s byte count 
quota and byte count limit 

EXE$DEBIT_BYTCNT Determines whether a job’s buffered byte 


count quota usage permits the process 
to be granted additional buffered I/O 
and, if so, adjusts the job's byte count 
quota 


EXES$DEBIT_BYTCNT_NW Same function as EXE$DEBIT_BYTCNT, 
but never places a process in a resource 
wait state pending the return of sufficient 
quota 
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Routine 
EXE$DEBIT_BYTCNT_BYTLM 


EXE$DEBIT_BYTCNT_BYTLM_NW 


EXE$DEBIT_BYTCNT_ALO 


EXE$DEBIT_BYTCNT_BYTLM_ALO 


Function 


Determines whether a job’s buffered byte 
count quota usage permits the process 
to be granted additional buffered |/O 
and, if so, adjusts the job’s byte count 
quota and byte count limit 


Same function as EXE$DEBIT_BYTCNT_ 
BYTLM, but never places a process in 

a resource wait state pending sufficient 
quota 

Same function as EXESDEBIT_BYTCNT, 
but, if quota checks succeed, allocates 
the requested amount of pool 

Same function as EXE$DEBIT_BYTCNT_ 
BYTLM, but, if quota checks succeed, 
allocates the requested amount of pool 


Many drivers written prior to VMS Version 5.0 contain code sequences similar 


to the following: 
JSB G"EXE$BUFFRQUOTA 


BLBC RO, ERROR 

JSB G*EXE$ALLOCBUF 
BLBC RO, ERROR 

MOVL PCB$L_JIB(R4) ,R5 
SUBL2 R1, JIB$L_BYTCNT(R5) 


;Would buffer allocation 

;exceed byte count quota? 

;Branch if yes 

;If not, allocate buffer 

;Branch if error 

;Obtain job information block 
;Decrement job's byte count quota 


The new routines allow you to simplify such code sequences. For instance, 

a single routine, EXESDEBIT_BYTCNT_ALO, checks and debits quotas and 
allocates pool. When there is not enough quota available to service the 
request, the routine restores the deducted amount and returns the error SS$_ 


EXQUOTA IN RO. 


In VMS Version 5.0, the preceding code example can be rewritten as follows: 


JSB G*EXE$DEBIT_BYTCNT_ALO 


BLBC RO, ERROR 


;Check for quota violation, 
;allocate buffer, decrement 
; JIB byte count quota 
;Branch if error 
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G.2.3 Referring to the Current PCB 


The symbol SCH$GL_CURPCB is obsolete and should be replaced as 
follows: 


e If the process’s P1 space is available, use the P1 space location 
CTL$GL _PCB. 


e If the process’s P1 space is not available, use the FIND_CPU_DATA 
macro, as follows: 


FIND_CPU_DATA RO 
MOVL §CPU$L_CURPCB(RO) ,R1 


The FIND_CPU_DATA macro obtains the virtual address of the per-CPU 
database for the processor on which it executes. Code that issues the 
FIND_CPU_DATA macro must adhere to the following rules: 


— It must be executing in kernel mode above IPL 2 when it invokes the 
FIND_CPU_DATA macro. 


— It must take care to prevent rescheduling after issuing the macro as 
long as the information returned by FIND_CPU_DATA is in use. It 
typically does this by remaining at an IPL greater than 2. 


G.2.4 Allocating System Page- Table Entries 


The system routine IOCS$ALLOSPT has been replaced by the 
LDR$ALLOC_PT. 


IOC$ALLOSPT was briefly described in Versions 4.5 and 4.6 of the VAX/VMS 
Release Notes as an appropriate method for non-DIGITAL-supplied VAXBI 
device drivers to map a portion of a device’s node space to system virtual , 
address space. See Appendix C for a full description of LDR$ALLOC_PT. 


G.2.5 Referring to a System Process Mailbox 


An existing driver that refers to either the job controller’s mailbox or 
OPCOM’s mailbox must be altered to use the new symbolic names that 
point to these mailboxes. Usually, it is the driver’s interrupt service routine or 
timeout handling routine that loads the address of the mailbox UCB into R3 
and calls the system routine EXES5SNDEVMSG, as follows. 


MOVAB G“SYS$AR_JOBCTLMB,R3 Set address of job controller 
; mailbox 
JSB G"EXE$SNDEVMSG ;Sent message to job controller 


The new symbolic names actually refer to global pointers to the mailbox UCB 
structures. They include the following: 
| VMS Version 5.0 Old . Name 


SYS$AR_JOBCTLMB SYS$AL_JOBCTLMB Job controller's mailbox 
SYS$AR_OPRMBX SYS$AL_OPRMBX OPCOM's mailbox 
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G.2.6 Reassembling and Relinking the Driver 


Because of changes in the definitions of data structures, the behavior of 
system macros, the location of global symbols, and the contents of system 
images, it is necessary to reassemble and relink non-DIGITAL-supplied 
drivers regardless of whether their contents have been modified. 


To do so, reassemble your driver against SYS$LIBRARY:LIB.MLB. For 
example: 


$ MACRO MYDRIVER.MAR+SYS$LIBRARY : LIB.MLB/LIBRARY 


Relink your driver against the VMS global symbol table. If the driver consists 
of several source files, you must specify the file that contains the driver 
prologue table as the first file in the list. The linker options file must contain 
the statement BASE=0. For example: 


$ CREATE MYDRIVER.OPT 

BASE=0 

$ LINK/NOTRACE MYDRIVERi[, MYDRIVER2,...],- 
MYDRIVER.OPT/OPTIONS, - 
SYS$SYSTEM: SYS .STB/SELECTIVE_SEARCH 


The linker will report that the image has no transfer address. You may ignore 
this message. 


Once you have linked or relinked a driver, you should copy its image to the 
SYS$LOADABLE_IMAGES or SYS$SYSTEM directory. The SYSGEN LOAD 
and CONNECT commands first search for a driver in the SYSSLOADABLE_ 
IMAGES directory. If they do not find the driver, they then search the 
SYSSSYSTEM directory. 


G.3 Adapting Device Drivers to Run on a VMS Multiprocessing System 


VMS Version 5.0 contains several new routines that enforce synchronization 
in a symmetric multiprocessing (SMP) environment. Drivers do not generally 
call these routines explicitly, but rather invoke VMS-supplied macros that 
synchronize as appropriate to the processing environment. There are only a 
few instances in which existing non-DIGITAL-supplied drivers must change 
to conform to the new synchronization mechanisms. This section outlines 
those instances; Chapter 3 describes synchronization rules in greater detail. 


G.3.1 Specifying the Fork Lock Index 


G-8 


To adapt a driver to execute properly in a VMS multiprocessor environment, 
you must replace all instances of UCB$B_FIPL (or FKB$B_FIPL) with 
UCB$B_FLCK (or FKB$B_FLCK). In addition, you must replace the 
invocation of the DPT_STORE macro that defined the driver’s fork IPL 
with one that defines the driver’s fork lock index, as follows: 


Old: DPT_STORE UCB,UCB$B_FIPL,B,8 
New: DPT_STORE UCB,UCB$B_FLCK,B,SPL$C_IOLOCK8 
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To use the new symbol, include the $UCBDEF structure definition macro 

in the driver. Fork lock (and other spin lock) indexes, such as SPL$C_ 
IOLOCK8, are defined by the $SPLCODDEF definition macro as invoked by 
DPTAB. Replace fork IPLs with the corresponding fork lock index according 
to the following list: 


IPL Fork Lock Index 


8 SPL$C_IOLOCK8 
2 SPL$C_IOLOCK9 
10 SPL$C_IOLOCK 10 
11 SPL$C_IOLOCK11 


All structure definition macros can be found in SYS$LIBRARY:LIB.MLB. 


Drivers rarely need to obtain a fork lock explicitly. VMS places the driver 
fork process into execution (originally by EXE$INSIOQ and, by implication, 
by IOC$REQCOM) at fork IPL holding the appropriate fork lock. In addition, 
the fork dispatcher obtains the fork lock associated with the driver fork 
process before it restores its context and resumes its execution. 


Note that, if a driver fork process is not placed into execution according to 
one of these means, it must obtain the fork lock itself. (See the discussion in 
Section G.3.6.2.) 


G.3.2 Synchronizing Access to the Device Database with the Interrupt Service 


Routine 


G.3.2.1 


The device database consists of device and adapter registers, plus driver- 
specific UCB fields that record the status of a device. As these locations 
are primarily accessed by the driver’s interrupt service routine, the driver 
fork process must take special care to synchronize with the interrupt service 
routine whenever it accesses them. 


Synchronizing at Device IPL 
Previous versions of VMS used the DSBINT macro to synchronize with the 
interrupt service routine at device IPL (UCB$B_DIPL), as follows: 


DSBINT UCB$B_DIPL(R5) ;Raise IPL to device IPL 
;Save current IPL on stack 
;Access device data 


ENBINT ;Restore saved IPL 
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Under VMS Version 5.0, this code should be modified so that it obtains the 
appropriate device lock, as follows: 


DEVICELOCK - ;Secure device lock 


LOCKADDR=UCB$L_DLCK (R5) , - ;(also raises IPL to device IPL) 
SAVIPL=- (SP) ;Save current IPL on stack 


;Access device data 


DEVICEUNLOCK - ;Release device lock 


LOCKADDR=UCB$L_DLCK (R5) , - 
NEWIPL=(SP) + -Restore old IPL from stack 


G.3.2.2 Raising IPL to IPL$_POWER 
If the device driver start-I/O routine (or fork process) raises IPL to IPL 31 
(IPL$_POWER) to check for the occurrence of a power failure and to access 
device registers, it must ensure that it has explicitly synchronized with the 
device’s database at device IPL. Under VMS Version 5.0, this means that the 
routine must first obtain the appropriate device lock, using the DEVICELOCK 
macro. 


Because versions of VMS prior to Version 5.0 allowed only one processor, 
even in a VAX multiprocessor system, to execute kernel-mode code, 

the following code in a driver’s start-I/O routine provided adequate 
synchronization: 


DSBINT ;Raise IPL to 31 
;Save current IPL on stack 
BBC #UCB$V_POWER, - 
UCB$W_STS(R5) ,30$ ;If clear, no power failure 
;Service power failure 


;Branch 
30$: ;Start device 


WFIKPCH 
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G.3.2.3 


Under VMS Version 5.0, the preceding code should be replaced with the 
following: 


DEVICELOCK - ;Secure device lock 
LOCKADDR=UCB$L_DLCK (R5) , - (also raises IPL to device IPL) 
SAVIPL=- (SP) ;Save current IPL on stack 

SETIPL #IPL$_POWER, - ;Raise IPL to 31 
ENVIRON=UNIPROCESSOR ;Avoid assembly-time warning 

BBC #UCB$V_POWER, - 

UCB$W_STS(R5) , 30$ ;If clear, no power failure 


;Service power failure 


DEVICEUNLOCK - ;Release device lock 


LOCKADDR=UCB$L_DLCK (R5) , - 
NEWIPL=(SP) + ;Restore old IPL from stack 
;Branch 


30$: ;Start device 


WFIKPCH ;Wait for interrupt 


Here, the DEVICELOCK macro achieves synchronized systemwide access 
to the device registers. The SETIPL macro then synchronizes the local 
processor against its own powerfail interrupt event. The code does not need 
to synchronize systemwide against powerfail events, because its interest is 
truly limited to the local processor. 


Note that the WFIKPCH macro releases the last acquisition of the device lock 
by the executing processor, restoring the old IPL prior to returning control to 
the caller’s caller. 


Refer to Chapters 3 and 8 for additional information on the synchronization 
rules imposed on a driver's start-I/O routine. 


Synchronization Within the Interrupt Service Routine 

As soon as it obtains the device unit’s UCB in R5, the driver’s interrupt 
service routine must issue the DEVICELOCK macro to synchronize with other 
code threads (such as the start-I/O routine and the timeout handling routine) 
that may access the device database at device IPL holding the device lock. 
Because the interrupt service routine is automatically called at device IPL, 
the DEVICELOCK macro invocation should specify condition=NOSETIPL. 
To save time, the macro should also specify preserve=NO so that code to 
preserve RO is not executed. 


For example: 


DEVICELOCK - ;Obtain device lock 
LOCKADDR=UCB$L_DLCK (R5) , - 
CONDITION=NOSETIPL, - ;Do not bother to set IPL 
PRESERVE=NO ;Do not save RO 
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Similarly, the interrupt service routine should release the device lock when it 
no longer needs to access the device database. Generally, this is immediately 
after the routine regains control from the driver fork process and before it 
restores the saved registers and issues an REI instruction, as follows: 


DEVICEUNLOCK - ;Release device lock 
‘LOCKADDR=UCB$L_DLCK (R5) , - 
PRESERVE=NO ;Do not save RO 
POPR #°M<RO,R1,R2,R3,R4,R5> ;Restore registers 
REI ;Exit from interrupt 


Refer to Chapters 3 and 9 for additional information on the synchronization 
rules imposed on a driver’s interrupt service routine. 


G.3.3 Controller and Unit Initialization Routines 


G.3.3.1 


As discussed in Section 11.1, a device driver’s controller and unit initialization 
routines are called during driver loading and reloading and during system 
recovery from a power failure. 


In a VMS symmetrical multiprocessing environment, any logic in a driver’s 
controller initialization routine or unit initialization routine that takes special 
action to service a power failure must adhere to the following rules: 


e It cannot acquire any spin locks. Controller and unit initialization routines 
are called at IPL 31 during power failure recovery to reinitialize I/O 
devices before the processors are allowed to proceed with execution at 
lower IPLs. Because processors may have been holding spin locks at 
the time of the power failure, they will not be able to release them until 
after they resume execution. As a result, spin locks are not available to 
controller and unit initialization routines. 


e It cannot perform any operation that requires the intervention of other 
processors in the system. 


Permanently Allocating Map Registers and Buffered Data Paths 
Because the map registers and buffered data paths of a UNIBUS adapter are 
shared by the devices residing on the bus, they are synchronized at a single 
fork IPL and, in a VMS multiprocessing system, by a single fork lock. 


Prior to VMS Version 5.0, a unit initialization routine that permanently 
allocated map registers or a buffered data path could do so at IPL$_POWER 
(its calling IPL). Under VMS Version 5.0, however, the map register and data 
path allocation routines require that the appropriate fork lock be held at the 
time of their calling. As a result, a unit initialization routine that permanently 
allocates these resources must fork before calling the allocation routine. The 
VMS fork dispatcher ensures that, when execution of the routine resumes, it 
is executing at fork IPL holding the fork lock. 


The consequences of forking in a unit initialization routine are discussed at 
length in Section 11.1.5. Refer to Sections 12.2.2.2 and 12.2.1.2 for additional 
information on permanently allocating map registers and buffered data paths, 
respectively. 
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G.3.4 Timeout Handling Routine 


In a VMS multiprocessing environment, the software timeout interrupt service 
routine calls a driver's timeout handling routine at device IPL, holding both 
the appropriate fork lock and device lock. 


Previous editions of this manual have suggested that a timeout handling 
routine can explicitly lower its IPL from device IPL to fork IPL using a 
SETIPL instruction. This action assumed that the thread of code that resulted 
in the call to the routine originated in a software interrupt granted at IPL 7 
(IPL$_TIMERFORK). 


-In a VMS multiprocessing system, such a forced lowering of IPL would break 


synchronization. In addition, similar assumptions about the origin of the 
calling code thread cannot be guaranteed. Instead, those timeout handling 
routines that must lower IPL should issue the IOFORK macro to fork. 


See Section 10.2 for additional information on the timeout handling routine. 


G.3.5 General Methods for Synchronizing Kernel-Mode Code 


G.3.5.1 


In addition to the changes in the driver routines explicitly discussed in 
Sections G.3.2 and G.3.3, there may be other alterations required in device 
drivers and other kernel-mode code before they can execute successfully in 
a VMS symmetric multiprocessing environment. This section provides some 
general discussion of these changes. You can find additional information on 
multiprocessing synchronization in Chapter 3. 


Using the Spin Lock Synchronization Macros 

You must adapt most kernel-mode code that raises or lowers IPL so that it 
obtains appropriate synchronization in a VMS multiprocessing environment. 
Determine these locations by searching for instances of the system macros 
SETIPL, ENBINT, and DSBINT or for an instruction such as MTPR x, PR$_ 
IPL (where x is an IPL value). Do not change those instances of the SETIPL 
and DSBINT macros intended to achieve synchronization only on the local 
processor. After careful inspection proves that the macro in question is 
intended to achieve local processor synchronization only, add the argument 
environ=-UNIPROCESSOR to their invocations. 


You should replace most instances of these macros with a LOCK, UNLOCK, 
FORKLOCK, FORKUNLOCK, DEVICELOCK, or DEVICEUNLOCK macro, 
as shown in Table G-3. You can substitute the appropriate usage of any 

of these macros wherever Table G-3 lists the LOCK and UNLOCK macros. 
The formats of the spin lock synchronization macros are fully described in 
Appendix B. Table 3-3 lists the system spin locks. 
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Table G-3 Converting IPL Synchronization to Spin Lock Synchronization 


Existing Macro 
SETIPL ip! (where ipl is 
greater than 2) 


SETIPL ipl (where ipl is 
greater than 2) 


SETIPL ipl (where ipl is 
less than 3) 
DSBINT ipl 


ENBINT 


G.3.5.2 


Function New Macro Function 

Raise IPL LOCK lockname, Raise IPL, acquire spin lock 
lockipl 

Lower IPL from an IPL UNLOCK Release spin lock, lower IPL 

greater than 2 ~ lockname, lockipl 

Lower IPL from an IPL SETIPL ipl Lower IPL 

less than 3 

Save current IPL and LOCK lockname, Save current IPL, raise IPL, 

raise to specified IPL lockipl, savipl acquire spin lock 

Lower IPL and restore UNLOCK Release spin lock, lower IPL 

saved IPL lockname, lockipl 


Interlocking Access to Data Cells and Queues 
VMS Version 5.0 assigns spin lock protection to system resources as described 


in Table 3-3. The system time and timer queue are managed under the 
TIMER and HWCLK spin locks, as detailed in Section 3.1.3. 


In a VMS multiprocessing environment, any thread of code that manipulates 
bit fields at different IPLs without spin lock protection must do so with 
interlocked instructions (for example, BBCCI and BBSSI).! Instances of 

the INSQUE and REMQUE instructions may need to be changed to use 

the INSQTI and REMQHI instructions, respectively, if they are issued to 
manipulate a queue at multiple IPLs. Certain cells, such as PCBSW_ASTCNT, 
must be incremented and decremented using an ADAWI instruction. INCx 
and DECx instructions are not interlocked in a VMS multiprocessing system. 


Spin locks explicitly protect various system queues and lists. For example, the 
AST queue in the process control block (PCB$L_ASTQEFL) is synchronized by 
the SCHED spin lock and the variable region of nonpaged pool is protected 
by the POOL spin lock. 


A fork lock implicitly protects the following adapter resource wait queues (at 
the specified listheads) at fork IPL, as long as the drivers for all devices on 
the adapter that require the resources use the same fork lock. 


Listhead 

VMS Version 

5.0 Old Name 

UCB$L_IOQFL Same Pending-I/O queue 

ADP$L_DPOFL Same UNIBUS buffered data path wait queue 

ADP$L_—MROFL Same UNIBUS/Q22 bus map register wait 
queue 

ADP$L_MR2QFL Same Q22 bus alternate map register wait 
queue 


Because a single spin lock cannot control access to list items that must 
be accessed by code threads executing at different IPLs, VMS Version 5.0 


" It is illegal to intermix interlocked and noninterlocked instructions that refer to the same bit: for instance BBCC 
and BBCCI. Should any noninterlocked instruction refer to the same bit, the bit is not interlocked. 
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provides either a processor-specific queue or a self-relative queue for such 
items. The following queues (at the specified listheads) are, under VMS 
Version 5.0, processor-specific queues whose forward and backward links are 
contained in the per-CPU database (described in Section A.4 and Table A-4). 


Listhead 


VMS Version 

5.0 Old Name 

CPU$SQ_SWIOQFL SWIS$GL_FOFL Software interrupt queue listhead 
CPU$L_PSFL IOC$GL_PSFL |/O postprocessing queue 


The following queues are, under VMS Version 5.0, self-relative queues whose 
forward and backward links are contained in the data area of the system 
loadable image SYSTEM_PRIMITIVES.EXE.? All system macros and routines 
that access these queues have been converted to access them with the INSQTI 
and REMQHI interlocked instructions. 


Listhead 


VMS Version 

5.0 Old Name 

lIOC$GO__SRPIO IOC$GL_SRPFL Nonpaged pool SRP lookaside list 
lIOC$GQ_LRPIO IOC$GL_LRPFL §Nonpaged poo! LRP lookaside list 
lOC$GO _IRPIQ lOC$GL_IRPFL Nonpaged pool IRP lookaside list 


G.3.6 Miscellaneous Conversion Tasks 


G.3.6.1 


This section describes those activities performed by some kernel-mode code 
threads that should be examined in the course of converting them to run in a 
VMS multiprocessing environment. 


Reading the System Time 

As discussed in Section 3.1.3, because EXE$6GQ_SYSTIME can only be 
changed or compared with multiple instructions, any code thread in a 
multiprocessing system that must obtain a consistent copy of the quadword 
must first acquire proper synchronization. 


VMS Version 5.0 supplies the READ_SYSTIME macro to simplify this 
procedure. It has the following format, where dst is the quadword destination 
where the macro returns the system time: 


READ_SYSTIME dst 
Use of the READ_SYSTIME macro is subject to the following restrictions: 
e IPL must be less than 23. 


a System cell EXE$AR_SYSTEM_PRIMITIVES contains the address of this image; the macro $$SYSTEM— 
PRIM_DATADEF in SYS$SYSTEM:LIB.MLB defines offsets into its data area. 
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G.3.6.2 


G.3.6.3 


G.3.6.4 


e¢ The processor must be executing in kernel mode. 


e When using the macro within pageable program sections executing at 
IPL 2 and below, you must ensure that the pages involved are locked in 
memory. 


Calling the Driver Fork Process from a TQE 

Whenever VMS places a driver fork process into execution, it ensures that 
it is synchronized with other processes at that fork level. In other words, if 
it is generated by the conclusion of I/O preprocessing (EXE$INSIOQ), the 
completion of a previous I/O request on a device unit (IOC$REQCOM), or 
the operation of the fork dispatcher, the driver fork process is placed into 
execution at the correct fork IPL, holding the corresponding fork lock. 


As an example, consider a driver fork process activated by a timer wakeup 
associated with a timer queue element (TQE) previously queued by the 
driver. The software timer interrupt service routine does raise IPL to IPL 8 
(IPL$_SYNCH) and obtain certain spin locks prior to dequeuing the TQE and 
placing it into execution, but it does not obtain the driver’s fork lock. Thus, 
even though the driver’s fork IPL may be IPL$6_SYNCH, the driver will not 
be properly synchronized at fork level unless it first obtains the appropriate 
fork lock. 


invalidating Translation Buffer Entries 

Prior to VMS Version 5.0, privileged code that changed a valid page-table 
entry (PTE) could flush the stale PTE from the processor’s translation buffer 
by using the INVALID macro or writing directly to the Translation Buffer 
Invalidate Single (TBIS) processor register. Similarly, it could invalidate 
the entire translation buffer by using the INVALID macro or writing to the 
Translation Buffer Invalidate All (TBIA) processor register. 


In a VMS Version 5.0 symmetric multiprocessing environment, processors 
must not use previously buffered PTE contents while another processor is 
changing that PTE. Once the PTE has been changed, other processors must 
flush the stale translation buffer entry for the PTE. To accomplish this, VMS 
has replaced the INVALID macro with the INVALIDATE_TB macro. 


The INVALIDATE_TB macro flushes a single PTE or all PTEs from the 
processor translation buffers in either a VAX uniprocessor or multiprocessor 
system. In updating privileged code for VMS Version 5.0, you must replace 
any instances of an INVALID macro or of an MTPR instruction to PR$_TBIS 
or PR$_TBIA with a suitable invocation of the INVALIDATE_TB macro. 


Appendix B contains a description of the INVALIDATE_TB macro. 


Unsupported Use of the IRP 

The VMS multiprocessing code employs a portion of the IRP (the 24 bytes 
following IRP$L_KEYDESC), previously used only as a fork block by the 
VMS disk and tape class drivers, to effect the transfer of an I/O request from 
a processor with no access to the device to another processor that does have 
access. 
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A driver that uses this portion of the IRP to store data can lose this data 
when the VMS I/O initiation routine (IOC$INITIATE) attempts to transfer the 
request to the driver’s start-I/O routine. VMS I/O initiation occurs when an 
FDT routine calls EXE$QIODRVPKT or when the driver issues the REQCOM 
macro to complete the current I/O request. 


G.3.7 Troubleshooting a Device Driver in a Multiprocessing System 


G.3.7.1 


If the full-checking synchronization image has been loaded into memory, 
the spin lock acquisition and releasing routines perform certain activities that 
aid in the debugging and tuning of a VMS multiprocessing system. These 
activities include the following: 


e Enforcement of the spin lock ranking and IPL requirements. The means 
by which the multiprocessing synchronization routines accomplish this 
are discussed in Section G.3.7.1. 


e Recording, for each spin lock, the last eight PCs that acquired or released 
the spin lock. These PCs are located at offset SPL6L_OWN-_PC_VEC in 
the spin lock data structure (SPL). You can use the SDA command SHOW 
SPINLOCKS/FULL to display the contents of the PC list. 


e Tallying, for each spin lock, the number of successful acquisitions and 
the number of failed acquisitions in SPL6Q_ACQ—COUNT and SPL$L_ 
BUSY_WAITS, respectively. 


Section G.1.1 explains the settings of the MULTIPROCESSING system 
parameter that produce the full-checking synchronization environment. 


The full-checking synchronization environment contains a mechanism | 

for producing bugcheck messages that describe the detection of serious 
synchronization problems in the system. In most instances, these problems 
are caused by a non-DIGITAL-supplied device driver that does not adhere to 
multiprocessing synchronization rules. 


This section describes the bugchecks that are possible in a VMS full-checking 
synchronization environment and the SDA commands that aid in the 
investigation of a multiprocessing system failure. It concludes with a brief 
description of VMS Version 5.0 changes to the XDELTA debugger. 


Multiprocessing Bugchecks 

In order to obtain a spin lock or fork lock, a processor must be executing at an 
IPL no higher than the lock’s synchronization IPL (SPL$B_IPL). Additionally, 
the processor cannot obtain a spin lock or fork lock if the lock’s rank (SPL$B_ 
RANK) is lower than that of any locks the processor currently holds. To 
release a spin lock, a processor must be executing at or above the IPL at 
which it originally acquired the lock. However, a processor can release spin 
locks in any order of rank. (See Table 3-3 for additional information on spin 
lock IPL and rank requirements.) 


In a full-checking synchronization environment, violation of spin lock 
synchronization will produce the bugchecks described in Table G—4. 
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Table G-4 Bugchecks Produced Within Full-Checking Synchronization 


SPLIPLHIGH 


SPLIPLLOW 


SPLACOERR 


SPLRELERR 


SPLRSTERR 


A processor has attempted to acquire a spin lock at an IPL higher than the IPL associated 
with spin lock synchronization (SPLSB_IPL). SMPSACQUIRE (called by the LOCK and 
FORKLOCK macros with condition=NOSETIPL not specified) signals this bugcheck. 


A processor has attempted to acquire a device lock—not already owned by the acquiring 
processor—at an IPL higher than the IPL associated with device lock synchronization 
(SPL$B_IPL). SMP$ACQUIREL (called by the DEVICELOCK macro with condition=NOSETIPL 
not set) signals this bugcheck. 


A processor has attempted to unconditionally or conditionally release a spin lock or device 
lock at an IPL lower than the IPL at which it originally acquired it. SMPSRELEASE and 
SMP$RESTORE (called by the UNLOCK and FORKUNLOCK macros) and SMP$RELEASEL or 
SMP$RESTOREL (called by the DEVICEUNLOCK macro) signal this bugcheck. 


A processor has attempted to acquire a spin lock while holding a higher ranked spin lock. 
SMP$ACQUIRE, SMP$ACQUIREL, and SMP$ACONOIPL (called by the LOCK, FORKLOCK, 
and DEVICELOCK macros) signal this bugcheck. 


An attempt has been made to completely release a spin lock not owned by the releasing 
processor. SMP$RELEASE and SMP$RELEASEL (called by the UNLOCK, FORKUNLOCK, and 
DEVICEUNLOCK macros) signal this bugcheck. 


An attempt has been made to conditionally release a spin lock not owned by the releasing 
processor. SMP$RESTORE and SMP$RESTOREL (called by the UNLOCK, FORKUNLOCK, 
and DEVICEUNLOCK macros when condition=RESTORE is specified) signal this bugcheck. 


G.3.7.2 Analyzing a Multiprocessing System Failure 


When invoked to analyze either a crash dump or a running system, the VMS 
System Dump Analyzer (SDA) establishes a default context for itself from 
which it interprets certain commands. 


When the subject of analysis is a VMS uniprocessing system, SDA’s context 
is solely process context. That is, SDA can interpret its process-specific 
commands in the context of either the process current on the uniprocessor or 
some other process in some other scheduling state. When initially invoked 
to analyze a crash dump, SDA’s process context defaults to the process that 
was current at the time of the crash. When invoked to analyze a running 
system, process context is initially that of the current process: that is, the one 
executing SDA. Change SDA’s process context by entering commands in any 
of the following forms: 


SET PROCESS /INDEX=nn 
SET PROCESS name 
SHOW PROCESS /INDEX=nn 


When invoked to analyze a crash dump from a VMS multiprocessing system 
with more than one active CPU, SDA maintains a second dimension of 
context—its CPU context—that allows it to display certain processor-specific 
information, such as the reason for the bugcheck exception, the currently 
executing process, the current IPL, the contents of processor-specific registers, 
the interrupt stack pointer (ISP), and the spin locks owned by the processor. 
When invoked to analyze a multiprocessor’s crash dump, the SDA CPU 
context defaults to that of the processor that induced the system failure. 


Note: When you use SDA to analyze a running system, CPU context is not 
accessible to SDA. As a result, the SET CPU and SHOW CPU commands 
are not permitted. 
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G.3.7.2.1 


Change the SDA CPU context by using any of the following commands: 


SET CPU cpu-id 
SHOW CPU cpu-id 
SHOW CRASH 


Changing CPU context involves an implicit change in process context in one 
of the following ways: . 


e If there is a current process on the CPU made current, SDA process 
context is changed to that of the CPU’s current process. 


e If there is no current process on the CPU made current, SDA process 
context is undefined and no process-specific information is available until 
SDA process context is set to that of a specific process. 


Changing process context can involve a switch of CPU context as well. For 
instance, if you enter a SET PROCESS command for a process that is current 
on another CPU, SDA will automatically change its CPU context to that of 
the CPU on which the process is current. The following commands can have 
this effect if the name or index number (nn) refer to a current process. 


SET PROCESS name 

SET PROCESS /INDEX=nn 
SHOW PROCESS name 
SHOW PROCESS /INDEX=nn 


Investigating the Status of Spin Locks : 

SDA in VMS Version 5.0 includes the command SHOW SPINLOCKS. The 
SHOW SPINLOCKS command displays various levels of information about 
system spin locks, fork locks, and device locks that help investigations of 
system failures caused by synchronization violations. 


For each spin lock, fork lock, or device lock in the system, SHOW 
SPINLOCKS provides the following information: 


e Name of the spin lock (or device name for the device lock) 

e Address of the spin lock (SPL) structure 

e The owner CPU’s CPU ID 

e IPL at which allocation of the lock is synchronized on a local processor 


e Number of nested acquisitions of the spin lock by the processor (depth of 
ownership) 


e Rank of the spin lock 
¢ Number of processors waiting to obtain the spin lock 


e¢ Spin lock index 


SHOW SPINLOCKS/BRIEF produces a condensed display of this same 
information. 


If the VAX system under analysis had been executing with full-checking 
synchronization enabled (that is, with the MULTIPROCESSING system 
parameter set to 1 or 2), SHOW SPINLOCKS/FULL adds to the spin lock 
display the last eight PCs at which the lock was acquired or released. 
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G.3.7.3 


Using XDELTA on SMP Systems 

Only one processor in a VMS multiprocessing environment can be in XDELTA 
at a time. If one processor attempts to enter XDELTA while another processor 
is using XDELTA, it waits until the other processor has exited XDELTA. If the 
processor using XDELTA sets a breakpoint, other SMP processors are aware 
of the breakpoint. Therefore, when the code with the XDELTA breakpoint 

is executed on another processor, that processor will stop at the specified 
breakpoint and wait to enter XDELTA. 


XDELTA uses its own system control block (SCB) to direct all interrupt 
handling to an error handling routine in XDELTA. Therefore, an error 
encountered by XDELTA will not affect any of the other processors which 
share the standard system SCB. 





Multiprocessing Implementation Details 


Processor States 


G-20 


In order to develop or maintain code that interacts closely with the operating 
system, a system programmer should be aware of certain aspects of the 
underlying operation of VMS that have been altered or introduced in 

VMS Version 5.0. The implementation of symmetric multiprocessing has 

its greatest effect on non-DIGITAL-supplied device drivers that must be 
adapted to run in a VMS multiprocessing environment. 


This section discusses the following operating system concepts, focusing on 
the effects of the Version 5.0 implementation of multiprocessing: 


e Processor states and state transitions 

e Initialization sequence of a VMS multiprocessing system 
e Process scheduling . 

e System timekeeping 


For information about multiprocessing synchronization and data structures, 
see Chapter 3 and Appendix A, respectively. 


A VMS multiprocessing system can be in one of several defined states, as 
illustrated in Figure G-1. 


Table G—5 


State 


Uniprocessor 


INIT 


TIMOUT 
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Figure G—1 Multiprocessor State Transitions 


boot timeout 
retries 
BOOT_REJECTED 


error after boot 










STOP/CPU 
STOPPED 





START /CPU STOP/CPU 


uniprocessor 





first attached successful boot 


processor boot BOOTED 









boot 
timeout 
(or) 
RESTART 
timeout 


ZK-6621-HC 


VMS boots initially as a uniprocessor and later creates a multiprocessing 
environment as part of system initialization (subject to the system parameters 
MULTIPROCESSING and SMP_CPUS). The DCL command START/CPU 
adds one or more available, inactive processors to the multiprocessing 
configuration. VMS stores a processor’s state (and other processor-specific 
data) in its per-CPU database structure. The DCL command SHOW CPU 
retrieves this information for display. 


Table G-5 describes the states defined for processors in a VMS 
' multiprocessing system. State transitions are depicted in Figure G-1. 


Multiprocessor States 


Description 


The multiprocessing system implicitly begins processing as a uniprocessor prior to 
any attempt to bring a secondary processor into the system. 


A secondary processor enters the INIT state during system initialization if the SMP_ 
CPUS system parameter indicates that this processor is to be booted. Alternatively, 
a processor enters the INIT state when it is the object of a START/CPU command. 
Should the bootstrap operation fail, a timeout mechanism causes VMS to retry the 
operation a defined number of times. If it has not successfully bootstrapped after 
these attempts, the secondary processor enters the TIMOUT state. 


A secondary processor enters the TIMOUT state when it fails to boot after a defined 
number of retries. If it is subsequently the object of a START/CPU command, 

the secondary enters the INIT state for another series of retries of the bootstrap 
operation. 
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Table G—5 (Cont.) 
State 
RUN 


BOOTED 


BOOT_REJECTED 


STOPPED 


TIMOUT_CRASH 


Multiprocessor States 
Description 


A secondary processor enters the RUN state when it successfully boots at the 
request of the primary processor and passes a series of processor validation checks. 
The primary processor itself is always in the RUN state. RUN is the normal state for 
all processors running in a multiprocessing environment. A processor in the RUN 
state is a formal member of the active set, actively participating in operating system 
activity in concert with other members of the active set. A secondary processor 
may exit the RUN state if it is the object of a STOP/CPU command. Additionally, a 
secondary can exit the RUN state if the primary processor requests a machine restart 
and the restart mechanism fails to restart the secondary. 


A secondary processor enters the BOOTED state when, after completing all normal 
operations to enter the RUN state, it must wait for the primary processor to 
complete the initialization of the multiprocessing environment. When in the BOOTED 
state, the secondary processor is running, but has has not yet been allowed by the 
primary to join the active set. 


A secondary processor enters the BOOT_REJECTED state upon successfully 
booting at the request of the primary, but failing the series of processor validation 
checks that ensure that all processors in a multiprocessing system are at equivalent 
hardware and firmware revision levels. To force its exit from the BOOT_REJECTED 
state, you must issue a STOP/CPU for its CPU ID prior to powering it down for 
repair. 


A secondary processor enters the STOPPED state when it is the object of a 
STOP/CPU command. You can issue the STOP/CPU command only for a processor 
in the RUN or BOOT_REJECTED state. A subsequent START/CPU command causes 
the secondary processor to enter the INIT state. 


When a secondary processor in the RUN state is restarting at the request of 

the primary (for instance, following a system power failure), a successful restart 
results in no transition from the RUN state. However, a failure to restart the 
secondary indicates that a critical processor resource has been lost. In this event, 
the secondary processor enters the TIMOUT_CRASH state and VMS induces a 
bugcheck. 





System Initialization 
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A VMS multiprocessing system initially boots as a uniprocessor. At this time, 
the primary processor is responsible for initializing system memory, loading 
VMS, and other system tasks. Because the primary CPU is the processor to 
which the console subsystem is physically or logically connected, it generates 
the output of all software messages to the console from any processor in the 
system. The primary CPU is also responsible for keeping system time. 


When the primary CPU first enters program mode, the primary bootstrap 
program (VMB) has been loaded into memory, and its stack pointer register 
points to the end of a physical page that VMB later formats as a restart 
parameter block (RPB). The primary CPU uses the end of the RPB as a boot 
stack until VMS memory management is enabled, when the interrupt stack in 
its per-CPU database is used. (See Appendix A for additional information on 
multiprocessing data structures.) 
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VMB loads the secondary bootstrap program (SYSBOOT) into memory 

and transfers control to it. Among its tasks in the creation of a VMS 
multiprocessing environment, SYSBOOT reserves sufficient system resources 
for the creation of an individual per-CPU database structure, boot stack, and 
interrupt stack for each processor in the system’s available set; that is, for 
all processors that can be brought into the system’s active set. SYSBOOT 
also must load an appropriate system synchronization image into memory, 
based on the setting of the MULTIPROCESSING system parameter for 

the primary processor. Table G-1 describes the contents of the three 
possible synchronization images. Table G-2 lists the possible settings of 
the MULTIPROCESSING system parameter. 


SYSBOOT completes its part in system initialization and transfers control to 
the INIT module of the VMS executive. In addition to its traditional duties, 
INIT completes the initialization of the primary processor’s per-CPU database 
and calls the SMP$SETUP_SMP entry point in the system-dependent 
initialization code (module SYSLOAxxx). This processor-dependent code 

has the responsibility of completing the multiprocessing initialization of a 
VAX system. 


First, SMP$SETUP_SMP performs the following general initialization tasks: 


e Places the address of the interprocessor interrupt service routine into the 
system control block (SCB). 


e Allocates a page of memory to serve as a boot page. It then inserts into 
this boot page code that is immediately executed by each processor in the 
system as it comes on line. It also stores data in the boot page required 
by each booting processor before it enables memory management. 


e Establishes a vector containing the physical addresses of all known per- 
CPU databases. A newly bootstrapped processor accesses this vector as 
it begins execution in order to locate its per-CPU database area. The 
physical address of this vector is found in the RPB. 


¢ Determines the processors that are to be brought into the system’s active 
set, using the value of the SMP_CPUS system parameter. 


The second phase of system-dependent initialization occurs in the system 
routine SMP$SETUP_CPU, which executes once for each processor indicated 
in the SMP_CPUS system parameter. Also, it is SMP$SETUP_CPU that 
executes whenever a START/CPU command attempts to place a secondary 
processor in the active set. 


SMP$SETUP_CPU performs the following functions: 


e  Allocates sufficient system resources (such as system page-table entries 
and page frame numbers) to map the per-CPU database and stacks of the 
processor. 


e Maps the SPTEs to the page-frame numbers (PFNs) of the allocated 
physical memory. 


e Initializes as much of the per-CPU database as possible. Later, the newly 
executing processor will complete this initialization. 


e Executes the processor-specific procedure that actually bootstraps the 
starting processor into the multiprocessing environment. 
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As each processor in the VMS multiprocessing system begins execution, it 
performs the following steps: 


e Locates its per-CPU database 


e Sets up any immediate context that it requires before enabling memory 
management 


e Enables memory management 
e Loads the interrupt stack pointer 
e Completes the initialization of its per-CPU database 


e Lowers IPL and begins processing as a member of the active set of the 
VMS multiprocessing system 


G.4.3 Scheduling ina VMS Multiprocessing Environment 
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With VMS Version 5.0, the scheduler no longer schedules a null process. 
Rather, all idle processors run in an idle loop at IPL 3 on the interrupt stack. 
Within this loop, the scheduler monitors SCH$GL—COMOS, the global cell 
that records the availability of computable inswapped processes. Each set bit 
in the longword corresponds to a process priority level at which there exist 
currently computable processes. When a process becomes computable, the 
bit in SCH$GL_COMOQS corresponding to its priority is updated under the 
SCHED spin lock. 


When an idle processor determines that a computable process exists, it 
contends for the SCHED spin lock, along with all other idle processors that 
have noted the change to SCH$GL_COMOS. Because only one processor 

at a time can enter the database protected by the SCHED spin lock, work is 
dispatched to each processor as it is able to secure the SCHED spin lock, until 
an inswapped computable process is scheduled on each active processor. 


While a processor runs in the idle loop, its CPU$L_CURPCB field points 

to the null PCB, and its CPU$B_CUR_PRI field contains 255, representing 
the highest priority process. This arrangement prevents code in RSE (report 
system event) from issuing a RESCHED request when a process becomes 
computable and the processor is actually idle. Thus, a processor issues a 
RESCHED request only when it must preempt the current process. With VMS 
Version 5.0, idle processors avoid the overhead involved in rescheduling the 
null process. 


For performance monitoring purposes, the time each processor spends 
executing on the interrupt stack at IPL 3, with the CPU$L_CURPCB field 
pointing to the null PCB, is counted as both null time and interrupt stack 
time. As recorded in the per-CPU database structure, null time is correct. To 
determine that portion of interrupt stack time that does not include null time, 
you must first subtract null time from the interrupt stack time. 


As a result of this implementation, VMS Version 5.0 ensures only that 
the n-highest real-time priority computable processes on an n-processor 
multiprocessing system will be current simultaneously. However, if all 
processes are of normal priority, VMS only guarantees that the highest 
priority normal process capable of running in the system will be scheduled. 


VMS Version 5.0 and Kernel-Mode Code 


G.4 Multiprocessing Implementation Details 


G.4.4 Timekeeping ina VMS Multiprocessing Environment 


Each processor in a VMS multiprocessor system has its own interval timer 
that, every ten milliseconds, causes a hardware interrupt at the interval clock’s 
IPL (either IPL 22 or 24, depending upon processor type). The interval clock 
interrupt service routine runs on each processor to service these interrupts, 
but portions of this routine are reserved to run on only one processor in the 
system, the primary CPU. By default, the boot CPU is also the primary CPU, 
as it is the processor to which the console subsystem is physically attached. 


The primary CPU has the sole responsibility of updating system data 
structures that maintain system time. Similarly, the primary CPU must 
examine the first entry in the systemwide timer queue to determine whether 
the first timer queue element (TQE) has expired, and request a software timer 
interrupt at IPL$_TIMERFORK (IPL 7) if it has. The IPL$_TIMERFORK 
interrupt service routine thereupon removes entries from the head of the 
timer queue until it has dispatched all due TQEs. 


Given this strategy, VMS Version 5.0 supplies two spin locks for the timer 
queue: 


HWCLK Interval clock database spin lock. Locks the interval clock database. 


TIMER Software timer database spin lock. Locks the rest of the system timer 
queue. 


The following example describes how VMS uses these two spin locks: 


When servicing an interval clock interrupt, the primary CPU performs the 
following sequence of tasks: 


1 Obtains the HWCLK spin lock, thus locking the interval clock database 


2 Advances the system time stored in EXE$GQ—SYSTIME by ten 
milliseconds 


3 Compares the due time of the first TQE (EXE$GQ—1ST_TIME) with 
EXE$GQ_SYSTIME to determine whether the first TQE has expired 


4 If it has, requests a software interrupt at IPL$_TIMERFORK 
5 Releases the HWCLK spin lock, thus unlocking the interval clock database 


When servicing a software timer interrupt at IPL$_TIMERFORK, the primary 
processor performs the following tasks: 


1 Obtains the TIMER spin lock, thus locking the software timer database 
2 Obtains the HWCLK spin lock, thus locking the interval clock database 


3 Compares the due time of the first TQE (EXE$GQ_—1ST_TIME) with 
EXE$GQ_SYSTIME to determine if the first TQE has expired 


4 If the first TQE has expired, removes it and resets EXE$GQ—1ST_TIME 
to reflect the due time of the TQE now at the head of the queue 


5 Releases the HWCLK spin lock, thus unlocking the interval clock database 
6 Releases the TIMER spin lock, thus unlocking the software timer database 
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When inserting a TQE into the timer queue, any processor performs the 
following tasks: 


1 Obtains the TIMER spin lock, thus locking the software timer database. 


2 Searches the timer queue to determine the proper place to insert the 
TQE in the queue. (If the TQE belongs at the head of the timer queue, it 
obtains the HWCLK spin lock, thus locking the interval clock database.) 


3 Inserts the TQE in the timer queue. (If it has inserted the TQE at the 
head of the queue, it resets EXE$GQ_—1ST_TIME to reflect the due time 
of the TQE and then releases the HWCLK spin lock.) 


4 Releases the TIMER spin lock, thus unlocking the software timer 
database. 


Non-DIGITAL-supplied system code that must access the system time 
quadword (EXE$GQ_SYSTIME) must do so after acquiring the HWCLK 
spin lock. See Section G.3.6.1 for some guidelines on how such code should 
perform these tasks. 
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ACF: See configuration control block. 
ACP: See ancillary control process. 


adapter control block (ADP): A structure in the I/O database that describes an I/O 
adapter (or VAXBI device) and its resources: 


active set: In a VMS symmetric multiprocessing system, those processors that have 
been bootstrapped into the system, have undergone initialization, and are capable 
of scheduling and executing processes. Together, the primary processor and all 
secondary processors make up a system’s active set. Compare with available set. 


ADP: See adapter control block. 


allocate a device: To reserve a particular device unit for exclusive use. A user process 
can allocate a device only when that device is not allocated by any other process. 


ancillary control process (ACP): A process that acts as an interface between user 
software and an I/O driver. An ACP provides functions supplemental to those 
performed by the driver, such as file and directory management. 


Examples of ACPs are the magnetic tape ACP (MTAACP) and the network ACP 
(NETACP). 


affinity: In a VMS symmetric multiprocessing system, a close association of a device 
or a process with a specific processor or set of processors in the system. See device 
affinity and process affinity. 


assign a channel: To establish the necessary software linkage between a user process 
and a device unit before a user process can communicate with that device. A user 
process requests the system to assign a channel and the system returns a channel 
number. 


AST: See asynchronous system trap. 
ASTLVL: See asynchronous system trap level. 


asynchronous system trap (AST): A software-simulated interrupt that passes control 
to a user-defined routine. ASTs enable a user process to be notified of the occurrence 
of a specific event asynchronously with respect to the execution of the user process. 


If a user process has defined an AST routine for an event, the system interrupts 
the process and executes the AST routine when that event occurs. When the AST 
routine exits, the system resumes execution of the process at the point where it was 
interrupted. 
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asynchronous system trap level (ASTLVL): A value kept in an internal processor 
register that is the highest access mode for which an AST is pending. The AST does 
not occur until the current access mode drops in privilege (rises in numeric value) to 
a value greater than or equal to ASTLVL. Thus, an AST for an access mode will not 
be delivered while the processor is executing in a more privileged access mode. 


available set: In a VMS symmetric multiprocessing system, those processors that have 
passed the system’s power-on hardware diagnostics and may or may not be actively 
involved in the system. The available set includes the active set. Compare with 
active set. 


ASMP: See asymmetric multiprocessing. 


asymmetric multiprocessing (ASMP): A multiprocessing configuration in which 
the processors are not equal in their ability to execute operating system code. In 
general, a single processor is designated as the primary, or master, processor; other 
processors are the slaves. The slave processors are limited to performing certain 
tasks, whereas the master processor can perform all system tasks. Contrast with 
symmetric multiprocessing. 


attached processor: See secondary processor. 


backplane interconnect: An internal processor bus that allows I/O device controllers 
to communicate with main memory and the central processor. These I/O controllers 
may reside on the same bus as memory and the central processor (for instance, in 
a VAX 8200/8250/8300/8350 system), or they may be on a separate bus entirely 
(for instance, in a VAX 8600/8650/8670 system). In the latter case, an I/O adapter 
enables and controls the communications between the I/O bus and the processor 
and memory. 


The backplane interconnect is called the synchronous backplane interconnect (SBI) 
in the VAX-11/780 and VAX 8600/8650/8670 systems, the CPU-to-memory 
interconnect (CMI) in the VAX-11/750 system, the VAXBI in the VAX 8200/ 
8250/8300/8350 systems, and the memory interconnect (NMI or XMI) in VAX 
8530/8550/8700/8800/8830/8840 and VAX 6200-series systems. The 

MicroVAX II and MicroVAX I processors use the Q22 bus as a backplane. 


base register: A general register that contains the base address (the address of the first 
entry) of a list, table, array, or other data structure. 


buffered data path: A UNIBUS adapter data path that transfers several bytes of data in 
a single backplane-interconnect transfer. 


buffered 1/O: An I/O operation, such as terminal or mailbox I/O, in which an 
intermediate buffer from the system's buffer pool is used instead of a buffer in 
process space. See also direct I/O. 


bugcheck: The operating system’s diagnostic that detects and reports internal 
inconsistencies. If the system can continue running, it declares a nonfatal bugcheck 
and reports it in an error log entry. A serious error results in a fatal bugcheck. Asa 
result of a fatal bugcheck, the system shuts itself down in an orderly fashion. 


busy wait: See spin wait. 


CALL instructions: The processor instructions CALLG (Call Procedure with General 
Argument List) and CALLS (Call Procedure with Stack Argument List). 
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capability: In a VMS symmetric multiprocessing environment, an attribute of a single 
processor or set of processors. The capabilities required by a given process determine 
the set of processors on which it can be scheduled. For instance, the VMS routine 
that maintains the system time can execute only on the processor that has the 
timekeeper capability. 


CCB: See channel control block. 


channel: A logical path connecting a user process to a physical device unit. A user 
process requests the operating system to assign a channel to a device so the process 
can communicate with that device. See also controller data channel. 


channel control block (CCB): A structure in the I/O database maintained by the 
Assign-I/O-Channel system service to describe the device unit to which a channel is 
assigned. 


channel request block (CRB): A structure in the I/O database that describes the 
activity on a particular controller. The CRB for a controller contains pointers to the 
queue of drivers waiting to access a device through the controller. 


configuration control block (ACF): A structure in the I/O database used by the 
autoconfiguration facility of the System Generation Utility to describe the device it is 
adding to the system. The information stored in the ACF might be useful to a device 
driver’s unit delivery routine. 


configuration register: A control and status register for an I/O adapter (for example, a 
UNIBUS adapter). It resides in the adapter’s I/O space. 


connect-to-interrupt: A function by which a process connects to a device interrupt 
vector. To perform a connect-to-interrupt, the process must map to the physical 
pages in the I/O space that contain the vector. 

console: The manual control unit integrated into the central processor. The console 
includes a serial-line interface connected to a hardcopy terminal. This enables the 
operator to start and stop the system, monitor system operation, and run diagnostic 
programs. 

console terminal: The terminal connected to the central processor’s console. 


context: The environment of an activity. See also process context, hardware context, and 
software context. 


controller data channel: A logical path to which the driver of a device that shares a 
controller must gain access before it can use the controller to activate a device. 


control and status register (CSR): A control and status register for a device or 
controller. It resides in the processor's I/O space. 


CRB: See channel request block. 
CSR: See control and status register. 


database: A collection of related data structures; all the occurrences of data described 
by a database management system. 


data structure: Any table, list, array, queue, or tree whose format and access 
conventions are well defined for reference by one or more images. 
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DDB: See device data block. 
DDT: See driver dispatch table. 


device affinity: In a VMS symmetric multiprocessing system, a close association of a 
device with a specific processor or set of processors in the system. There are three 
dimensions to device affinity in a VMS system. First, physical connectivity describes 
those devices that are directly accessible only to the primary processor or to all 
processors. Secondly, affinity is a software mechanism that defines those processors 
that can initiate an I/O operation on the device. Finally, interruptibility describes 
the set of processors that can receive interrupts from a device. 


device data block (DDB): A structure in the I/O database that identifies the generic 
device/controller name and driver name for a set of devices that share the same 
controller. 


device driver: The set of instructions and tables that handles physical I/O operations to 
a device. 


device interrupt: An interrupt received on interrupt priority levels 20 through 23. 
Device interrupts can be requested only by devices, controllers, and memories. 


device lock: In a VMS symmetric multiprocessing system, a dynamic spin lock the 
ownership of which synchronizes device-specific code that executes at device IPL. A 
device lock is associated with each adapter or controller in the system. See spin lock. 


device register: A location in controller logic used to request device functions (such as 
I/O transfers) and/or report status. 


device unit: One device and its controlling logic (for example, a disk drive or terminal). 
Some controllers can have several device units connected to a single controller (for 
example, mass-storage controllers). 


diagnostic program: A program that tests hardware, firmware, peripherals logic, or 
memory, and that reports any faults it detects. 


direct data path: A UNIBUS adapter data path that transfers several bytes of data ina 
single backplane-interconnect transfer. 


direct I/O: An I/O operation in which VMS locks the pages containing the associated 
buffer in physical memory for the duration of the I/O operation. The I/O transfer 
takes place directly from the process’s buffer. Contrast with system buffered I/O. 


direct-memory-access (DMA) transfer: The type of I/O transfer by which a device 
controller accesses memory directly and, as a result, can transfer a large amount 
of data without requesting a processor interrupt after each of the smaller amounts. 
Contrast with programmed-I/O (PIO) transfer. 


DPT: See driver prologue table. 


drive: The electromechanical unit of a mass storage device on which a recording 
medium (disk cartridge, disk pack, or magnetic tape reel) is mounted. 


driver dispatch table (DDT): A table in a driver that lists the addresses of the entry 
points of standard driver routines and the sizes of diagnostic and error message 
buffers for the device. 
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driver prologue table (DPT): A table in a driver that describes the driver and the type 
of device it controls to the VMS procedure that loads drivers into the system. 


dynamic load balancing: A method of work distribution in which the operating 
system ensures that the system work load is evenly distributed among the 
processors. Dynamic load balancing in a VMS symmetric multiprocessing system 
is a direct effect of the implementation of the scheduler. In a VMS multiprocessing 
system, processors independently and continually look for processes to execute from 
a common pool of such processes. 


ECC: Error-Correction Code. 


error logger: A system process that empties the error logging buffers and writes the 
error messages into the error file. Errors logged by the system include memory 
errors, device errors and timeouts, and interrupts with invalid vector addresses. 


exception: An event detected by the hardware or software (other than an interrupt or 
jump, branch, case, or call instruction) that changes the normal flow of instruction 
execution. 


An exception is always caused by the execution of an instruction or set of 
instructions (whereas an interrupt is caused by an activity in the system that is 
independent of the current instruction). 


There are three types of hardware exceptions: traps, faults, and aborts. Examples 
are attempts to execute a privileged or reserved instruction, trace traps, page faults, 
compatibility-mode faults, execution of breakpoint instructions, and arithmetic traps. 


executive: The software that provides the basic control and monitoring functions of the 
operating system. 


extended QIO processor: The facility that supplements the QIO driver’s functions 
when the driver performs virtual I/O operations on file-structured devices (Files—11 
On-Disk Structure Level 2). The XQP executes as a kernel-mode thread in the 
process of its caller. 


FDT: See function decision table. 


FDT routines: Driver routines called by the $QIO system service to perform device- 
dependent preprocessing of an I/O request. 


fork block: That portion of a data structure, such as the unit control block, which 
contains a driver’s context while the driver is waiting for an event or a resource. 
A driver awaiting the processor resource has its UCB fork block linked into a 
processor-specific fork queue. 


fork dispatcher: A VMS interrupt service routine that is activated by a software 
interrupt on the local processor at a fork IPL. Once activated, it obtains the fork 
lock associated with the fork IPL and dispatches driver fork processes from a fork 
queue until no processes remain in the queue for that IPL. 


fork lock: In a VMS symmetric multiprocessing system, a static spin lock the ownership 


of which synchronizes the right of a driver’s fork process to execute at its associated 
fork IPL. See spin lock. 
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fork process: A process with a minimal context that executes instructions under a set 
of constraints: it executes at raised interrupt priority levels; it uses RO through R5 
only (other registers must be saved and restored); it executes in the system’s virtual 
address space; it can refer to and modify static storage that is never modified by 
procedures that execute at a higher IPL. VMS uses software interrupts, spin locks, 
fork processes, and resource wait queues to synchronize executive operations. 


fork queue: A processor-specific queue of fork blocks that are awaiting activation at a 
particular IPL by the VMS fork dispatcher. 


function code: See I/O function code. 

function decision table (FDT): A table in the driver that lists all valid function codes 
for the device and lists the addresses of preprocessing routines associated with each 
valid function of the device. 

function modifier: See I/O function modifier. 

generic device name: A device name that identifies the type of device but not a 
particular unit; a device name in which the specific controller and/or unit number is 


omitted (for example, MB). 


hardware context: The values contained in the following registers while a process is 


executing: 
¢ The PC 
¢ The PSL 


° The 14 general registers (RO through R13) 


¢ The four processor registers (POBR, POLR, P1BR and P1LR) that describe the 
process’s virtual address space 


¢ The SP for the access mode in which the processor is executing 


¢ The contents to be loaded in the SP for every access mode other than the current 
access mode 


When a process is executing, its hardware context is continually being updated by 
the processor. When a process is not executing, its hardware context is stored in its 
hardware PCB. 


hardware process control block (hardware PCB): A data structure known to the 
processor that contains the hardware context when a process is not executing. A 
process’s hardware PCB resides in its process header (PHD). 


IDB: See interrupt dispatch block. 


interrupt: An event other than an exception or a branch, jump, case, or call instruction 
that changes the normal flow of instruction execution. Interrupts are generally 
external to the process executing when the interrupt occurs. See also device interrupt, 
software interrupt, and urgent interrupt. 


interrupt dispatch block (IDB): A structure in the I/O database that describes the 
characteristics of a particular controller and points to devices attached to that 
controller. 
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interrupt priority level (IPL): The level at which a software or hardware interrupt 
is generated. There are 32 interrupt priority levels: IPL 0 is lowest, 31 is highest. 
The levels arbitrate contention for processor service. For example, a device cannot 
interrupt a processor if the processor is currently executing at an IPL greater than 
the IPL of the device’s interrupt request. 


interrupt service routine (ISR): A routine executed when a device interrupt occurs. 


interrupt stack (IS): The processor-specific stack used when the processor is executing 
instructions in interrupt context. In the VMS operating system, all hardware 
interrupts (and all software interrupts above IPL 3) are serviced on a processor- 
specific interrupt stack and not one of the perprocess stacks. 


interrupt stack pointer (ISP): The pointer to the top of the interrupt stack. 
interrupt vector: See vector. 


[/O database: A collection of data structures that describe 1/O requests, controllers, 
device units, volumes, and device drivers in a VMS system. Examples are the driver 
dispatch table, driver prologue table, device data table, unit control block, channel 
request block, I/O request packet, and interrupt dispatch block. 


1/O driver: See driver. 


I/O function: An I/O operation interpreted by the operating system and typically 
resulting in one or more physical I/O operations. 


I/O function code: A 6-bit value specified in a $QIO system service call that describes 
the particular I/O operation to be performed (such as, read, write, rewind). 


I/O function modifier: A 10-bit value specified in a $QIO system service call that 
modifies an I/O function code (for example: read terminal input, no echo). 


I/O lockdown: The state of a page such that it cannot be paged or swapped out of 
memory. 


1/O request packet (IRP): A structure in the I/O database that describes an individual 
I/O request. The $QIO system service creates an IRP for each I/O request. VMS 
and the driver of the target device use information in the IRP to process the request. 


1/O rundown: An operating system function in which the system cleans up any I/O in 
progress when an image exits. 


I/O space: The regions of physical address space that contain the configuration 
registers and device control and status register and data registers. These regions 
are physically noncontiguous. 


I/O status block (IOSB): A data structure associated with the $QIO system service. 
This service optionally returns a status code, number of bytes transferred, and 
device /function-dependent information in an I/O status block. The information 


is not returned from the system service call, but filled in by VMS when the I/O 
request completes. 


IPL: See interrupt priority level. 


IRP: See I/O request packet. 
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ISP: See interrupt stack pointer. 
ISR: See interrupt service routine. 


limit: The size or number of items requiring system resources (such as mailboxes, locked 
pages, I/O requests, or open files) that a job is allowed to have at any one time 
during execution, as specified by the system manager in the user authorization file. 
See quota. 


load balancing: A function of the operating system by which work is distributed 
equally among all processors in a system. For more information, see static load 
balancing and dynamic load balancing. 


locking a page in memory: Making a page ineligible for either paging or swapping. A 
page stays locked in physical memory until VMS specifically unlocks it. 


logical-I/O function: A set of I/O operations (for example, read-logical-block and 
write-logical-block) that allow restricted direct access to device-level I/O operations 
using logical block numbers. 


loosely coupled system: A multiprocessing system configuration consisting of 
separate operating systems that communicate through some message transfer 
mechanism. Contrast with tightly coupled system. 


mailbox: A software data structure that is treated as a record-oriented device for 
interprocess communication (for example, the error logger and OPCOM read from 
systemwide mailboxes). Communication using a mailbox is similar to other forms 
of device-independent I/O. Senders write to a mailbox; the receiver reads from that 
mailbox. 


machine check: An exception that is reported when the processor or an external 
adapter detects an internal error. If the machine check is recoverable, the machine 
check handler logs the condition in an error log entry. If an unrecoverable machine 
check occurs while the processor is in supervisor or user mode, the machine check 
handler reports the exception to that mode. However, if an unrecoverable machine 
check occurs in kernel or executive mode, a fatal bugcheck results. See also exception 
and bugcheck. 


map register: See scatter-gather map. 


MASSBUS adapter (MBA): An interface device between the backplane interconnect 
and the MASSBUS. 


memory interconnect: The name of the internal processor bus for the VAX-11/750 
(CMI), VAX 8530/8550/8700/8800/8830/8840 (NMI), and VAX 6200 series (XMI). 


multiprocessing system: A system containing two or more general purpose 
processors. These processors are connected through hardware so that they can 
work on the same application concurrently. See asymmetric multiprocessing and 
symmetric multiprocessing. 


multiprogramming: A mode of operation in which hardware resources are shared 
among multiple, independent software processes. 


nexus: A physical connection to the synchronous backplane interconnect (SBI). For 
example, when connected to the SBI, the central processor, memory subsystem, and 
I/O controllers are known as nexuses. See also synchronous backplane interconnect. 


Glossary 


node: A VAXBI interface—such as a central processor, controller, or memory 
subsystem—that occupies one of 16 logical locations on a VAXBI bus. See also 
VAXBI. 


offset: A displacement from the beginning of a data structure to the beginning of a field 
within that data structure. Offsets for items within a data structure usually have an 
associated symbol. The name of the symbol is used to refer to the field; its value is 
the offset. 


page-frame number (PFN): The high-order 21 bits of the physical address of a page 
in physical memory. 


page-table entry (PTE): The data structure that identifies the physical location and 
status of a page of virtual address space. When a virtual page is in memory, the PTE 
contains the page-frame number needed to map the virtual page to a physical page. 
When it is not in memory, the page-table entry contains the information needed to 
locate the page on secondary storage (disk). 


parallel processing: A method of computing that occurs when a section of an 
application is divided into multiple tasks, and those multiple tasks are executed 
simultaneously on multiple processors. 


PCB: See process control block. 
PEN: See page-frame number. 


physical address: The address used by hardware to identify a location in physical 
memory or on directly-addressable secondary storage devices such as disks. A 
physical-memory address consists of a page-frame number and the number of a byte 
within the page. A physical-disk-block address consists of a cylinder or track and a 
sector number. 


physical address space: The set of all possible physical addresses that can be used to 
refer to locations in memory (memory space) or device registers (I/O space). 


physical-1/O functions: A set of I/O functions that allows access to all device-level 
I/O operations except maintenance-mode operations. 


PID: See process identification. 


primary processor: The processor in a VMS symmetric multiprocessing system that 
is either logically or physically attached to the console device. Only the primary 
processor performs the initialization activities that define the VMS environment and 
prepare memory for the entire system. In addition, the primary processor serves as 
the system timekeeper. 


process: The basic entity, scheduled by the system software, that provides the context 
in which an image executes. A process consists of an address space, hardware 
context, and software context. 


process affinity: In a VMS symmetric multiprocessing system, a close association of a 
process with a specific processor or set of processors in the system. Process affinity 
can be indicated as either a requirement that a process run only on the processor 
with a specific CPU ID or on a processor or set of processors that have a needed 
capability. See capability. 


process context: The hardware and software contexts of a process. 
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process control block (PCB): A data structure used to contain process context. The 
hardware PCB contains the hardware context. The software PCB contains the 
software context, which includes a pointer to the hardware PCB. 


process identification (PID): A 32-bit value that uniquely identifies a process. Each 
process has a PID and a name. 


process I/O channel: See channel. 
process page tables: The page tables used to describe process virtual memory. 


process priority: The priority assigned to a process for scheduling purposes. The 
operating system recognizes 32 levels of process priority, where 0 is lowest and 31 
is highest. Levels 16 through 31 are used for real-time processes. The system does 
not modify the priority of a real-time process (although the system manager or the 
process itself might). Levels 0 through 15 are used for normal processes. The system 
can temporarily increase the priority of a normal process based on the activity of the 
process. 


Contrast with interrupt priority level. 


programmed-!/O (PIO) transfer: The type of I/O transfer, largely conducted by 
the driver program, that requires processor intervention after each byte or word 
is transferred. Drivers for relatively slow devices, such as printers, card readers, 
terminals, and some disk and tape drives use PIO data transfers. Contrast with 
direct-memory-access (DMA) transfer. 


program section (psect): A portion of a program with a given protection and set of 
storage-management attributes. Program sections that have the same attributes are 
gathered together by the linker to form an image section. 


PTE: See page-table entry. 


Q22 bus: The hardware interconnect by which MicroVAX-3600 series, MicroVAX 
II, and MicroVAX I peripheral devices communicate with main memory and the 
processor. 


QIO: Queue I/O Request system service. The VMS system service that services $QIO 
and $QIOW requests. The Queue I/O Request system service prepares an I/O 
request for processing by the driver and performs device-independent preprocessing 
of the request. This system service also calls driver FDT routines. See also FDT 

" routines. 


quota: The total amount of a system resource, such as CPU time, that a job is allowed 
to use in an accounting period, as specified by the system manager in the user- 
authorization file. See limit. 

return status code: See status code. 

SBI: See synchronous backplane interconnect. 

scatter-gather map: A technique by which a set of physically discontiguous pages are 
made to seem contiguous to an I/O controller performing a direct-memory-access 


transfer. It is 1/O adapter hardware that generally provides this means of mapping 
physical pages to I/O adapter address space. 
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secondary processor: The processor or processors in a VMS symmetric 
multiprocessing system that do not have the initialization and timekeeper 
responsibilities of the primary processor. 


small process: A system process that has no control region in its virtual address space 
and has an abbreviated context. Examples are the swapper and the null process. A 
small process is scheduled in the same manner as user processes, but must remain 
resident until it completes execution; it cannot be swapped. 


shared memory: A generic term referring to any memory that can be accessed by two 
or more concurrent processes. In a VMS symmetric multiprocessing system, a single 
copy of the VMS operating system resides in memory. Each processor in the system 
can access this memory, as can any process executing on any processor. 


SMP: See symmetric multiprocessing. 


software context: The context maintained by VMS to describe a process. See also 
software process control block (PCB). 


software process control block (software PCB): The data structure used to contain 
a process’s software context. The operating system defines a software PCB for every 
process when the process is created. 


The software PCB includes the following kinds of information about the process: 
current state; storage address, if the process is swapped out of memory; unique 
identification of the process; and address of the process header (which contains the 
hardware PCB). The software PCB resides in the system region of virtual address 
space. It is not swapped with a process. 


start-I/O routine: The routine in a device driver that is responsible for obtaining 
needed resources and for activating the device unit. An example of a needed 
resource is the controller’s data channel. 


spin lock: In a VMS symmetric multiprocessing system, a semaphore associated 
with a set of system structures, fields, or registers whose integrity is critical to the 
performance of a specific operating system task. There are two types of spin lock. 
Static spin locks are assembled permanently into the system; the same static spin 
locks exist in the same memory locations in all VMS multiprocessing systems. A 
fork lock is a form of static spin lock. Dynamic spin locks are created as required by 
the I/O configuration of a system; as a result, the set of dynamic spin locks differs 
from processor to processor. A device lock is a form of dynamic spin lock. See fork 
lock and device lock. 


spin wait: In a VMS symmetric multiprocessing system, an execution loop performed 
by a processor attempting to acquire a spin lock already owned by another processor 
in the system. This activity is also known as a busy wait. 


static load balancing: A method of work distribution in which every process in an 
application is preassigned to a processor during process creation. 


status code: A longword value that indicates the success or failure of a specific 
function. For example, system services always return a status code in RO upon 
completion. 


SVA: See system virtual address. 


Glossary—11 


Glossary 


symmetric multiprocessing (SMP): A multiprocessing system configuration in which 
all processors have equal access to operating system code residing in shared memory 
and can perform all, or almost all, system tasks. 


synchronous backplane interconnect (SBI): The part of the VAX-11/780, 
VAX-11/785, and VAX 8600/8650/8670 hardware that interconnects the processor, 
memory controllers, MASSBUS adapters, and the UNIBUS adapter. 


System Page Table (SPT): The data structure that maps the system virtual addresses, 
including the addresses used to refer to the process page tables. The SPT contains 
one PTE for each page of system virtual memory. The physical base address of the 
SPT is contained in a processor register called the System Base Register (SBR). 


system virtual address (SVA): A virtual address identifying a location mapped to an 
address in system space. 


tightly coupled system: A multiprocessing system configuration consisting of 
multiple processors sharing a single copy of the operating system. These processors 
are connected so that they can communicate and share data. Contrast with loosely 
coupled system. 


timeout: The expiration of the time limit in which a device is to complete an I/O 
transfer. The driver’s wait-for-interrupt request specifies the timeout limit. 


timer: A system process that maintains the time of day and the date. It is also alert for 
device timeouts and performs time-dependent scheduling upon request. The timer’s 
interrupt service routine creates the timer process. 


UCB: See unit control block. 


UNIBUS adapter: An interface device between the backplane interconnect and the 
UNIBUS. In a VAX-11/780, VAX-11/785, or VAX 8600/8650/8670 system this 
device is called the UBA. In a VAX-11/750 system, it is called the UBI. In a 
VAX 8200/8250/8300/8350 or VAX 8530/8550/8700/8800 system, it is called 
a DWBUA. 


unit control block (UCB): A structure in the I/O database that describes the 
characteristics of a device unit and current activity on it. The unit control block 
also holds the fork block for its unit’s device driver; the fork block is part of the 
UCB and is a critical part of a driver fork process. The UCB also provides a static 
storage area for the driver. 


unit initialization routine: The routine that readies controllers and device units for 
operation. Controllers and device units require initialization after a power failure 
and during execution of the driver-loading procedure. 


urgent interrupt: An interrupt received on interrupt priority levels 24 through 31. 
These can be generated only by the processor for the interval clock, serious errors, 
and power failures. 


VAXBI: The part of the VAX 8200/8250/8300/8350 hardware that connects I/O 
adapters with memory controllers and the processor. In a VAX 8530/8550/ 
8700/8800 system, the part of the hardware that connects I/O adapters with the 
bus that interfaces with the processor and memory. 
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vector: A one-dimensional array. 


An interrupt or exception vector is a storage location known to the system that 
contains the starting address of a routine to be executed when a given interrupt or 
exception occurs. The system defines separate vectors for each interrupting adapter 
and for classes of exceptions. Each system vector is a longword. 


For the purpose of handling exceptions, users can declare up to two software- 
exception vectors (primary and secondary) for each of the four processor-access 
modes. Each vector contains the address of a condition handler, and is a longword. 


virtual-1/O functions: A set of I/O functions that must be interpreted by an ancillary 
control process. 


wait-for-interrupt request: A request made by a driver's start-1/O routine after it 
activates a device. The request causes the driver’s fork process to be suspended until 
the device requests an interrupt or the device times out. 


XDELTA: A software tool for debugging the VMS operating system and device drivers. 
XQP: See extended QIO processor. 
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Aborting an 1/O request 


See |/O request 
ACB$V_QUOTA ®C-7, C-10 
ACB (AST control block) *4—18, A-38, A-64, 

C-2, C-4 

contents ® C-6 
Accessibility of memory 

See Buffer 
Access violation 

See SS$_ACCVIO 
ACF (configuration control block) ® A—2 to A-—4 
ACL (access rights list) A—45 
ACP (ancillary control process)* A—11, A-38, 

A-39, A-52 

See also XOP 

class ®° A-27 

default © A—27 
ACP_MULTIPLE parameter * A-27 
Action routine 

See FDT routine 
Action routine bit mask ¢ 4—10 
Active set ® G—23 
Adapter 

See |/O adapter 
Adapter control block 

See ADP 
Adapter dispatch table ® 12-27, 12-31, A-6, A-7 

address ® A—6 

examining ® 16-8 to 16-9 
ADP$L_AVECTOR ® 14—8 
ADP$L_BIMASTER® 14-8, 14-15 
ADP$L_BI_IDR® 14-8, 14-12 
ADP$L_CSR® 14-8, C-79 
ADP$L_DPOFL ® C-84, G-—14 
ADP$L_MBASCB ® 14-8, A—7 
ADP$L_MBASPTE ® 14-8, A—7 
ADP$L_MR2QOFL ® G—14 
ADP$L_MROFL ° G-14 
ADP$L_—VECTOR ® 12-31 
ADP$W_ADPTYPE ® 14-8, B-3 
ADP$W_BI_VECTOR® 14-8, 14-13 
ADP$W_DPBITMAP ® 12-17, C—93 
ADP$W_TRe 14-8, 14-15 


ADP$W_XBIA_TR® 14-15 
ADP (adapter control block)® 1-6, 12-15, 
A-4 to A-10 
address ® 4-5, 12-17, 12-19, 12-31, A-24, 
A-35 
alternate map register allocation information ® 
A-10 
alternate map register wait queue * A—9 
data path allocation information® 12-17, A-—9 
data path wait queue ® 12-17, A-7 
fields supporting ADPDISP macro ® B—3 
for generic VAXBI device ® 14—8 
for MBA® 13-4, 13-6 to 13-7 
for VAXBI adapter ® 14—8 
map register allocation information * A—9 
map register wait queue ®* A-8 
size e A—5 
ADPDISP macro® 5-5, B-2 to B-4 
examples ¢ B—4 
Affinity 
See Device affinity 
Alignment of data transfer ® 12-3 
Allocation class ® A—-27 
Alternate map registers ® 12—2, 12-5, 12-22, 
A-8, A-25, B-3 
See also Map registers 
allocating ® 12-19, C-61 to C-62 
allocating permanent ® 11—2, 12—20, A—25 
loading ® 12-22, B—41, C-72 to C~-73 
number of active * A—10 
number of disabled ® A—10 
releasing ® 12-26, B—48, C-81 to C-82 
requesting ®B—53, C-89 to C-90 
Alternate map register wait queue® A-9, C-—90, 
G-14 
Alternate start |/O routine® 7-5, C—17 
address ° 6—4, A-29, D-—2 
context ® D—2 
entry point * D—2 
exit method * D—2 
input * D—2 
register usage ¢ D—2 
synchronization requirements * D—2 
ARB (access rights block) ® 4-8, A—41 
AST (asynchronous system trap) ®C-—6 to C-—7 


See also Attention AST 
control ® A—64 
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AST (asynchronous system trap) (cont’d.) 
delivering ® 3-4, C-2, C-11 
for aborted !/O request ®* C—11 
out of band® 11-7, A-64 
process-requested ® 4—18, C—7, C—10, C—71 
queuing ® 3-4, C—71 
special kernel-mode ¢ 3-4, 4-17, 7-7, 
7-7 to 7-8, A-11 
user specified * A-38 
AST control block 
See ACB 
ASTLVL (AST level) processor register ¢ 3—4 
AST procedure (for connect to interrupt facility) © 
18-18 
AST service routine (for connect to interrupt 
facility)® 18-8, 18-10, 18-12 
AT$_MBA ¢ A—32 
AT$_UBA ® A-32 
Attached processor 
See Secondary processor 
Attention AST 
See also AST 
blocking e A-61, A-62 
delivering e C—2 
disabling * C—6 to C-—7 
enabling * C—6 to C—7 
flushing ¢ C—4 
Attention condition ® 13-8 to 13-9 
See also MBA, MBA$L_AS, MASSBUS 
Attention summary register 
See MBA$L_AS 
Autoconfiguration 
See also System Generation Utility 
driver control of 15-17 to 15-18 
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Backplane interconnect ® 1-11, 1-15, 12-1 
See also VAXBI, CMI, SBI, Q22 bus 
Backplane interconnect interface chip 
See BIIC 
BADDALRQOSZ bugcheck *¢ C-3, C—19 
BI 
See VAXBI bus 
BIIC 
CSR space ® 14-5 
BUC$L_BCICR® 14-13, 14-26 to 14-27 
BIIC$L_BER® 14-6, 14-12, 14-13, 
14-24 to 14-25 
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BIIC$L_BICSR® 14-11, 14-23 to 14-24 
BIIC$L_DTREG® 14-6, 14-23 
BIICSL_EAR ® 14—26 
BIIC$L_EICR® 14-9, 14-13, 14-25 to 14-26 
BIIC$L__GPRO ® 14-28 
BIICSL_GPR1° 14-28 
BIIC$L__GPR2 © 14—28 
BIIC$L_GPR3 ¢ 14-28 
BIIC$L_IDR®* 14-12, 14-26 
BIIC$L_IPIDR® 14-26 
BIICSL_IPIMR ® 14-26 
BIIC$L_IPISR® 14—26 
BIIC$L_IPISTPF ® 14-27 
BIICSL_SAR ® 14-26 
BIIC$L_UICR® 14-9, 14-13, 14-27 to 14-28 
BIIC$L__WSR ® 14-27 
BIICSV_ARBCNTRL® 14—11 
BItC$V_BROKE ¢ 14—11 
BIIC$V_SST e 14-11 
BIIC$V_STS ® 14-11 
BIIC (backplane interconnect interface chip) * 14—5 
clearing error register ® 14-12 
enabling error interrupts® 14-13, 14-25 
enabling options ® 14—13. 
initializing ® 11—2 
self test® 14-11 
setting interrupt vectors ® 14-13 
$BIICDEF macro® 14—5, 14-21 
BIIC registers 
accessing ® 14—5 
symbolic names® 14-21 to 14-28 
BIOCNT (buffered I/O count) ¢ 2-3 
BIOLM (buffered 1/O limit) quota 
adjusting ®°4—17 
charging ®4—7, 4-10 
checking ® 4—7 
for mailbox ¢ A—52 
BIRO level® 12-34, 12-35 
BI-to-UNIBUS adapter 
See DWBUA 
BOOTED processor state ® A~15, G—22 
Booting with XDELTA® 16-1 to 16-5 
Boot page * G—23 
Boot stack ® A-14 
BOOT_REJECTED processor state® A-15, G-—22 
BPT (Breakpoint) instruction ® 16—6 
Breakpoint 
clearing © 16—18 
complex ® 16-18 
displaying XDELTA breakpoint list® 16-18 
proceeding from® 16-5, 16—18 


Breakpoint (cont’d.) 
setting in driver code® 16-6, 16-10, 16-17 
BREAKPOINTS parameter ® 16—1, 16-5 
BR level ® 12-34 
relation to SCB vectors ® A—9 
Buffer 
allocating ® 1-18, 2-3, 7-6 to 7-7, 
C-12 to C—13, C—14, C-15, 
C-22 to C-23, G-5 
allocating a physically contiguous ® 12-26, 
C-16 
data area® 7-6 
deallocating ®2—7, 4—17, 7-7, C-3, C-19 
format ® 7-7 
header area® 7—6, 7—7 
locking® 1-18, 6-7, A-41, A-—42, 
C-31 to C-33, C-34 to C-36, 
C-—40 to C-42, C-45 to C-47, 
C-53 to C-54, C-—57 to C-58 
locking multiple areas ®°C-—34, C-45, C—57 
moving data from system to user ® C—78 
moving data from user to system ® C—77 
size® 7-6, 12-26 
storing address of * 7-6 
testing accessibility of © 7-6, B-36 to B-37, 
C-31 to C-33, C-34 to C-—36, 
C-40 to C-—42, C-43 to C-—44, 
C-45 to C-47, C-53 to C—54, 
C-—55 to C—56, C-57 to C—58 
unlocking ¢ C—105 
Buffer address register ® 12—22 
Buffered data path® 12—8, A-8 
See also Data path 
allocating permanent® 11-2, 12-18, A-24, 
G-12 
flow of read operation using® 12-12 to 12-13 
flow of write operation using ® 12—12 
functions ® 12-11 
odd transfer ® A—8 
purging ® 12-13, 12-19, 12—24to 12-25, 
C-79 to C-80 
releasing® 10-2, 12-19, 12-25, B—50, C-84 
requesting® 12-11, 12-17 to 12-18, B—55, 
C-93 to C-94 
rules for using® 12—11, 12-14 
speed ® 12-14 
Buffered data path wait queue 
See Data path wait queue 
Buffered function bit mask® 4—9, 6-7 
Buffered 1/O* 1-18, 2-3, 4-9, 11-6, 14-16, 
A-39, A-40, A-58 
chained ¢ A—39 
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Buffered |/O (cont’d.) 
complex ® A-39 
FDT routines for® 7-6 to 7-8 
functions ¢ 6-4 
postprocessing® 7-7 to 7-8, C-70 
reasons for using ® 1-18, 6—7 
Buffered read function bit 
See IRP$V_FUNC 
Bugcheck ® 16—20 
BADDALROSZ ¢ C-3, C—19 
examining information regarding ® 16—5 
ILLOBUSCFG ® A-20 
INCONSTATE ® C-85, C-94 
SPLACOERR ® 16-25, 16-26, C-—107, G—18 
SPLIPLHIGH ¢ 16-25, C-107, C—108, G—18 
SPLIPLLOW ¢ 16-25, C-109, C—110, C-111, 
C-112, G-—18 
SPLRELERR ® 16-25, 16-26, C-—109, C—110, 
G-18 : 
SPLRSTERR® 16-25, 16-26, C—111, C-112, 
G-18 
UBMAPEXCED ¢ C—73, C—76 
UNSUPRTCPU ¢ B-9 
BUGREBOOT parameter ® 16-2, 16-5, 16-20 
Bus grant® 12-34, 12-35 
Bus request 
See BR level, BIRQ level 
Busy bit 
See UCB$V_BSY 
BYTCNT (byte count) quota ® 3-12 
checking ® G—5 
crediting ® C-18, G—5 
debiting ® C-12, C-20 to C-21, 
C-22 to C-23, G—5 
system maximum ¢ C—20, C—22 
verifying ® C-20 to C-21, C-22 to C-—23 
Byte count quota 
See BYTCNT 
Byte count register 
See MBA$L_BCR 
Byte limit 
See BYTLM 
Byte offset register ® 12-13 
BYTLM (byte limit) 
crediting * G—5 
BYTLM (byte limit) quota ® 3-12 
checking ® G—5 
crediting * C—18 
debiting® C-12, C-20 to C-21, 
C-22 to C-23, G-—5 
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Cache control block * A-62 
Caching * A-54 
CAN$C_CANCEL® 11-7 
CAN$C_DASSGN ® 11-7 
Cancel I/O bit 


See UCB$V_CANCEL 
Cancel 1/O routine® 1-4, 9-7, 11-6 to 11-8, 
A-29 . 
address ®°6-3, 11-1, D-3 
context ® 11-7, D—4 
device dependent® 11-8 
device independent ® 11-8 
entry point ® D—3 
exit method ¢ D—4 
flushing ASTs ine C—4 
for connect to interrupt facility® 18-8, 18-10, 
18-17 to 18-18 
input ¢D-—4 
of CONINTERR.EXE ® 18-12, 18-17 
register usage * D—4 
synchronization requirements * D—4 
when unneeded ® 1 1—7 
$CANDEF macro ® 11—7 
Card reader ® A—54 
device driver® 9-6 to 9-8 
Carriage control * A-53 
CASE macro ® B—5 
example ® B—5 
CCB$B_AMOD ®¢ C—100 
CCB$L__UCB ® 4—4 
CCB (channel control block)* 1-6, 4-4, A-11 
address ¢ C—100 
Channel® 1-6 
See also Process |/O channel 
Channel control block 
See CCB 
Channel index number ® 4—4, 11-8, C-66, C-—100, 
D—4 
Channel request block 
See CRB 
Channel wait queue 
See Device controller data channel wait queue 
CHMK (Change Mode to Kernel) instruction * 4—1 
$CINDEF macro® 18-10 
Class driver 
See Terminal class driver 
Class driver entry vector table * A~-33 
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Class driver vector table® 17-5, A-67 
address ® 17-8, B-7 
relocating ® B—6 
CLASS_CTRL_INIT macro® 17-11, A-67, B-6 
CLASS_DDT vector table entry ® 17—18 
CLASS_DISCONNECT service routine ® 17—18 
CLASS_DS_TRANS service routine® 17-11, 
17-18 
CLASS_FORK service routine® 17-13, 17-18 
CLASS_GETNXT service routine® 17-19, A-67, 
B-7 . 
address ® 17-8 
CLASS_POWERFAIL service routine® 17-11, 
17-20 
CLASS_PUTNXT service routine® 17-16, 17-19, 
A-67, B-7 
address ® 17-8 
CLASS_READERROR service routine ® 17-16, 
17-21 
CLASS_SETUP_UCB service routine ® 17-11, 
17-20 
CLASS_SET_LINE service routine ® 17-11 
CLASS_UNIT_INIT macro® 17-8, 17-11, 17-18, 
B-7 
Clock 
See Interval clock 
Cloned UCB routine® 11-11 to 11-12, A—56 
address ® 6-4, A-30, D-—5 
context ® D—5 
exit method® 11-12, D—6 
input® 11-11, D—5 
register usage ® 11-11, D—5 
synchronization requirements ® D—5 
CMI (CPU-to-memory interconnect) ¢ 1-11 
Coding conventions 
See Device driver 
COM$DELATTNAST ¢ C—2 
COM$DRVDEALMEM ® 14—18, C—3 
COM$FLUSHATTNS ® C—4, C-6 
COM$POST ¢ 3-4, 7-5, C-5, D- 
COM$SETATTNAST ®C-6 to C— 
Command address register 
See MBA$L_CAR 
Configuration register 
See CSR, MBA$L_CSR 
CONFREGL array ® 14—6 
CONINTERR.EXE ® 18-7, 18-12 to 18-13 
cancel !/O routine of ® 18-12 
connecting to ® 18-8 
CONNECT command 
See System Generation Utility 
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Connect to interrupt driver 
See CONINTERR.EXE 
Connect to interrupt facility 
cancel I/O routine® 18-17 to 18-18 
condition values returned ® 18-11 
CONNECT command ® 18-8 
example of A/D converter using ® 18-18, 
18-20 to 18-22 
example of time sampling using ® 18-18, 
18-22 to 18-24 
example of watchdog timer using® 18-18, 
18-19 to 18-20 
interrupt service routine® 18-16 to 18-17 
mapping |/O address space * 18-7 
privileges required ® 18—11 
programming language requirements ® 18-13 
start 1/O routine ® 18-15 
SYSGEN requirements © 18-8 
unit initialization routine ® 18-14 to 18-15 
user-specified routines ® 18-8, 18-13 to 18-18 
Control and status register 
See CSR 
Control block 
See Data structure 
Controller 
See Device controller 
Controller initialization routine ® 1-3, 
11-1 to 11-6, 15-4, 15-8 
address ® 4—4, 6-3, 11-1, 12-31, A-23, 
B-24, D-7 
allocating controller data channel in ¢ 8—4 
context® 11-1, D-7 
entry point © D-—7 
exit method ¢ D—7 
for generic VAXBI device® 14-10 to 14-15 
forking ® A—19 
forking ine 3-21, 11-5 to 11-6 
for terminal port driver® 17-11, B-6 
functions ® 11—1, D-8 , 
input ® 11-2, D-7 
register usage * D—7 
synchronization requirements ®*D—7, G—12 
Control mask 
See Device activation bit mask 
Control register 
See CSR, MBA$L_CR 
Coroutine ® C—35, C-46, C—58, C-105 
Corruption 
detecting® 16-22 to 16-24 
CPU$L_PHY_CPUID ¢ C-68 
CPU$L_PSBL®C-5, C-10, C-—24, C-92 
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CPU$L_PSFL® 3-5, C-70, G-15 
CPU$O__SWIOFL ® C-26, C-—30, G—15 
CPU$O_WORK_IFO * A-16 
CPU (per-CPU database) ® A—12 to A-17 
creation * G—23 
locating ®B—29, G—7 
CPUDISP macro ® 5-5, B—-8 to B-9 
CPU ID* A-16, C-68 
CRB$B_MASK ¢ 4—4, 14-7 
CRB$L_AUXSTRUC ¢ 12-26 
CRB$L__DLCK ¢ 3—20 
CRB$L_INTD ®4—4, A-20 to A-25 
CRB$L_INTD+VEC$L_INITIAL © 11-4 
CRB$L_INTD+VEC$L-__UNITINIT © 11—4 
CRB$L_LINK © 13-12 
CRB$L_WOBL ® 14-7 
CRB$L_WOFL® 4—4, 14-7, C-83, C-88 
CRB$V_UNINIT ¢ 14-7 
CRB (channel request block)® 1-6, 4—4 to 4-5, 
A-17 to A-25 
alternate map register allocation information ® 
12-20 
creation ® 15—4 
data path allocation information ® 
12-17 to 12-18 
for generic VAXBI device ® 14-7 
fork block ® 3—21, 15-7, A-19 
for MBA® 13-4, 13-6 to 13-7, 13-12, 
13-14 
initializing *6—3, B—24 
map register allocation information ® 
12-19 to 12-20 
periodic wakeup of ® A—20 
primary ® 13-12, A-—52 
reinitializing © 6-3, B—24 
secondary ® 13—12, A—20 
synchronizing access to® 3-15 
CSR 
fixed space ® 15-12 
floating space ® 15-12 
CSR (control and status register)® 12-4, 12-22 
See also Device registers 
address ° 4-5, 8-4, 12—23, A-35 
bad address ¢ A-35 
displaying address ® 15-9 
loading ¢ 8-5 
locating device registers from® 12—23 
of LP11 printer® 2—5 
specifying address ® 15-5 
specifying offset for multiunit controller ® 15—5 
CTL$GL_CCBBASE ® C—100 
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index 


CTLSGL_PCB ° G-7 


D 


Data pathe 1-17, 12-8to 12-14, 
12—17 to 12-19, A-24 
See also Buffered data path, Direct data path 
autopurging ® A-8, B-3 
buffered ® 12-2, A-8, B-3 
direct *B-3 
mixed use of direct and buffered® 12—19 
purging® 10-2, 12-13, 12-19, 
12-24 to 12-25, B-46, C-79 to C-80 
speed® 12-10, 12-11, 12-14 
Data path allocation bit map * A—9 
Data path register® 12—8, 12-15 
purge error ® C—80 
Data path wait queue ® 12—25, A—7, C—-85, C-94, 
G-14 
Data storage ® 5—1 
device specific® 4—4, 11-2, A~40, A—47, 
B-20 
Data structure * A—1 
See also |/O database 
defining bit field withine B—70 to B-71 
defining field within® B—12, B—13, B—14 
initializing ®6—1, B-22 to B-24 
Data transfer 
See also DMA transfer, PIO transfer 
alignment ® 12-3 
byte aligned® 12-2, 12-22, B—3, C—-76 
byte count® A~58, A-62 
byte offset® 12-13, 12-18, A-58, C-75 
in reverse direction® 13-3, 13-13 
longword-aligned 32-bit random-access ® 
12-11 
mixing read and write functions in® 12—10 
negative byte count *C—32, C-35, C-41, C-43, 
C-—45, C—54, C—55, C-57 
overlapping with seek operation ® 8—3 
size ® 12-23 
speed® 12-10, 12-11, 12-14 
starting address® 12-22 to 12-23, 12-26, 
~A-58 
to randomly ordered addresses ® 12-10 
word aligned ® 12—2, C-76 
zero byte count ®C—32, C-—41, C-54 
$DCDEF macro® A-54, B-3, B-19 
DDB$L_LINK ® 11-4 
DDB$L_UCB ® 11-4 
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DDB$ST_DRVNAME ® 4-6 
DDBST_NAME ¢ 4-6 
DDB (device data block)* 1—5, 4-6, 11-4, 
A-25 to A-27 

address ® A~52 

creation ® 15-4 

initializing ° 6-3, B-24 

reinitializing © 6-3, B—24 
DDT$L_ALTSTART ¢ 7-5, D-2 
DDT$L_CANCEL ¢ D-3 
DDT$L_CLONEDUCB ¢ D-5 
DDT$L_REGDUMP ¢ D-14 
DDT$L_START eD-15 
DDT$L_UNITINIT ¢ 11-4, D-21 
DDT$L_UNSOLINT ¢D-—23 


-DDT$W_ERRORBUF e 11-9 


DDT (driver dispatch table)® 1-2, 11-1, 11-9, 
A-27 to A-30, C-99 
address ®° 6-3, A-27, A-58, B—24 
creating® 6-3 to 6—4, 11-3,B-—10 to B-11 
of terminal class driver® 17-18 
relocating addresses specified in® 11—4 
DDTAB macro® 11-9, 15-1, B-—10 to B—11, 
C-99 
example ® B—11 
Debugging 
device driver® 16-1 to 16-27 
$DEFEND macro ® A—48, B-13 
example ® B—14 
$DEFINI macro * A—48, B-14 
example ¢ B—14 
$DEF macro® A—48, B-12 
example ¢ B—14 
DELTA 
See Delta/XDelta Utility 
Delta/XDelta Utility (DELTA/XDELTA) ¢ 
16-1 to 16-20 
base register ® 16-13 
predefined ® 16-13 
X4° 16-13 
X5° 16-13 
XE*® 16-13 
XFe 16-13 
changing contents of location using ® 16—15, 
16-16 
closing location using ® 16—16 
commands 
executing string® 16—19 
indirect ® 16—17 
predefined in XE and XF® 16-13 
summary ® 16-10 to 16-12 


Delta/XDelta Utility (DELTA/XDELTA) (cont’d.) 
depositing command string in system patch 
space for use by® 16-19 
displaying contents of address range using ® 
16-16 
displaying contents of location using * 16-16 
expressions ® 16—12 
formats 
address display ® 16—15 
instruction display * 16-16 
guidelines ® 16—20 
prefixes 
Ge 16-13 
H* 16-13 
setting PC with® 16—18 
stepping through code with * 16-19 
symbols 
period (.)® 16-13 
Q¢16-13, 16-16, 16-17 
using in multiprocessing environment® 16-7, 
G-—20 
values ® 16-12 
DEV$V_AVL® 17—20 
DEV$V_ELGe 11-9, C-8 
DEV$V_NET ° 17-12 
DEV$V_RED e 17-20 
$DEVDEF macro *® A-53, A—-54 
Device 
See also Device unit 
allocation class ®* A—27 
associated mailbox * A—56 
bus ® A-54 
byte-addressable * 12-22 
card reader ® A—54 
cluster accessible *® A-52 
cluster available e A—54 
DIGITAL-supplied® 15-12 to 15-13 
directory structured ¢ A—53 
disk ® A-54, C-50, C-—92 
dual ported ® A-53, A-54 
file structured ® 2-3, 4-8, A-27, A-53 
input ® A-53 
line printer ¢ A—54 
mailbox ® A-53, A—54 
mounted ® A-53, A—56 
mounted foreign ® A—53 
network ® A-53 
offsettable ® 14-9 
on VAXBI bus ® 14-2 
output * A-53 
random access ® A—53 
real time ® A-53, A-54 


Index 


Device (cont’d.) 


record oriented ® A~53 
reference count ® A—57 
sequential block-oriented * A—53 
shareable * A—53 
spooled ¢ A-53 
synchronous communications ® A—54 
tape e A-54, C-92 
terminal¢ A~53, A-54 
timed out * A-56 
word-aligned ® 12-18 
workstation ¢ A—54 
Device activation bit mask © 8—4 
Device affinity ® A-54, C-69 
Device allocation lock ¢ A—52 
Device characteristics ®° 7-8, A-—53 to A-54 
retrieving * C—48 
setting ® C—49 to C-—50 
specifying *6—2, B—24 
Device class ® A~54 
specifying ®°6—2, B—24 
Device controller® 1-5, 1-6, A-17 
See also MBA, Controller initialization routine 
initializing © 11-1 
intelligent ® 1-18 
multiunit © 3-23, 4-4, 4-14, 8-3, 8-6, 9-8, 
A-35, A-52, A-55 
number of units created for® 15-6, B—20 
number of units supported by® A—33, A-35, 
A-36, B—20 
reinitializing © B—20 
single-unit® 3-24, 4-5, 10-2, 11-2, 15-2, 
A-35 
status ® A~—20 
synchronizing access to® 3-15 
Device controller channel wait queue * 3-24 
Device controller data channel® 4—4 to 4—5, 
13-12, 13-14 
See also Secondary controller data channel 
obtaining ownership of ® 3-23, 4-4, 
8-3 to 8-4, A-35, B-57, C—97 to C-98 
owner @ 4—5 
releasing ® 3-24, 8-6, 10-2, B—49, C-83 
releasing before waiting for interrupt *C—102 
relinquishing ownership ® B—72 
requesting * 8-3 
retaining ownership ® B—72 
retaining while waiting for interrupt * C—102 
unavailability * 8—3 
Device controller data channel wait queue ® 8-3, 
A-19, C—83, C-88, C-98 
Device database 3-5, 3-15, G-9 
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Device database (cont’d.) 
synchronizing access to®3—19 to 3-20, 
B-15 to B—-16 
Device data block 
See DDB 
Device driver ® 1—1 
assembling with SYS$LIBRARY:LIB.MLB ¢ 15—1, 
G-8 
asynchronous nature®1—1, 1-8 to 1-9, 5-1 
branching on adapter characteristics ¢ 
B-2 to B-4 
branching on processor type ®B-8 to B-9 
calculating base address ® 16—7 
coding conventions ® 5-1 to 5-3, 15-1, 
16-21, 16-21 
components® 1-2 to 1-4, 5-1 
context® 1-7 to 1-9 
converting uniprocessing to multiprocessing ® 
G-8 to G-20 
debugging® 16-1 to 16-20 
displaying address of * 15-10 
entry points® 1-2, 6-3 to 6-4, A-27, 
D-—1 to E-1 
example ®E—1 to E-29, F—-1 to F-25 
flow® 1-8 to 1-9, 1-19to 1-21 
for generic VAXBI device® 14—1 to 14-28, 
C-103 
for MASSBUS device* 13-1 to 13-15 
for Q22 bus device® 12-1 to 12-36 
for UNIBUS device® 12—1 to 12-36 
~ functions © 1-2 
hardware considerations® 1-9 to 1-16 
implementing a conditional wait *B-63, B-64 
linking with SYS$SYSTEM:SYS.STB ¢ 15—1, 
16-7, G-8 
loading® 6-1, 11-3 to 11-4, 13-6 to 13-7, 
15—1 to 15-20, 16-5, A-32 
machine independence ® 1-10, 5-5, 12-16, 
B-2 to B-4, B-8 to B-9 
maximum number of supported units ® 6-2 
multiprocessor ® 15-10, G—1, G-3 
name® 4-6, 15-3, 15-6, 15-7, 15-9, A-27, 


A-33, B-—20 

program sections ® 6-3, 15-1, 16-7, B—11, 
B-19 

reloading® 15-7 to 15-8 

size® 5-1, A-32 


storing data from ® 5—1 
suspending ® 2-6, 8-6 to 8-7, 12—24, A-52 
synchronization flow ®3-—16 to 3-19 
synchronization methods used by ® 1-7, 

3-1 to 3-24 
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Device driver (cont’d.) 


template for®5—-6 to 5-15 
uniprocessor ® 15—10, G—1, G—3 
unloading ® A~32, B—20 
Device interrupt® 1-6, 3-5, 4-14, 9-1 to 9-8, 
12-27 to 12-35 
See also Interrupt service routine 
destination for VAXBI node ® 14-8 
direct-vector® 12—2, 12-28, 12-30, 12-32, 
A-7, A-8, A-23, B-3 
disabling ®°5—4, 10-4 
enabling ® 2-5, 11-2 
expected ®8-—7, 9-3 to 9-4, A-56, C—102 
multilevel Q22 bus® 12-32, 12-34 to 12-36, 
A-20 
non-direct-vector® 12—2, 12-29, 12-30, 
12-32, A-7, A-—23 
on MASSBUS ¢ 13-8 
servicing ® 2-6 
unsolicited® 9-4 to 9-8, A-29 
waiting for¢ 2-5 to 2-6, 4-14, 8-6 to 8-7, 
12-24, B—73, C-101 to C—102 
Device interrupt vector ® 12-27, 14-8, 14—9 
connecting to® 18-7 to 18-24 
for generic VAXBI device ® 14—13 
multiple © 12-32, 14—7 
specifying address ® 15-6 
specifying multiple ¢ 15—6 
Device IPL® 3-5, 9-1, A-55, B-15 to B—16 
specifying ® 6-2, B-24 
Device lock® 3-6, 3-12, 3-15, 8-5, A-47, 
A-56, C-102 
See also Spin lock 
acquisition IPL®¢ C—108 
address ® 3-20, A~20, A-35, A-52 
multiple acquisition of °B—17, C-112 
obtaining 3-9, B—15 to B-16, C-106, C-108 
ownership ® 3—15 
rank © 3-15 
releasing * 3-9, B—17 to B-18, C-—110 
restoring ®B-17, C-112 
DEVICELOCK macro ® 3—8, 3-9, B—15 to B-16, 
B-61, B—72, C—106, C—108, G—4, G—10, 
G-11 
example ®e B—16, B—18, B-61 
used by interrupt service routine * 9-3 
Device mode ® 7-8 
Device name® 1-5, A—27 
Device registers® 1-6, 1-16 to 1-18, 12-23 
accessing ® 2-5, 4-5, 12-4, 12-23, 14-5, 
16-20 to 16-21, 18-1, A-23, A-35, 
B-15 to B-16 


Device registers (cont’d.) 


clearing error status ® 11-1 
modification by power failure * 8—5 
modifying ® 5—3 
of LP11 printer ®2—5 
rules for referencing ®5—3 to 5—4, 12-4 
saving the value of © 11-10, D—14 
synchronizing access to® 3-5, 3—15, 8-5 
Device timeout 
See Timeout 
Device timeout bit 
See UCB$V_TIMOUT 
Device type ® A—54 
specifying ° 6-2, B—24 
Device unit® 1-5, A-47 
See also UCB, Unit initialization routine 
activating ® 2-5, 8-4 to 8-5, 12-23 
allocating ® A-52, A-53, A-56 
autoconfiguring® 15—19 to 15-20, B—20 
busy indicator ® A-56 
CSR address ® 15—9 
deaccessing ® A-11 
deallocating * A-56 
description ® 4—4 
error retry count ® A—58 
initializing © 11—1 
marking available * A—53 
marking on line® 11-2, A—56 
name ° 4—6 
number ® A—55 
operations count ® C—-92 
reference count® 11-6, D-3 
reinitializing ¢ B—20 
status °4—4, A-56 to A-57 
vector address ® 15-9 
DEVICEUNLOCK macro ® 3-9, B—17 to B—18, 
B-61, C-110, C-112, G—4, G-11, G-12 
example ¢B-—16, B—18, B-61 
issued by IOC$WFIKPCH and IOC$WFIRLCH @ 
C-—102 
Diagnostic buffer®e 4-18, A-—39, A—41, A-57, 
A-62, C-69 
copied to process space ® C—71 
filling © C-67 
size ® A-29 
specifying ° 4-8, 6-4 
Diagnostic register 
See MBA$L__DR 
DIOLM (direct I/O limit) quota 
adjusting ® 4-17 
charging ®°4—7, 4—10 


Index 


DIOLM (direct I/O limit) quota (cont’d.) 
checking ® 4—7 
Direct data pathe 12-8, 12-10 
See also Data path 
functions ® 12—10 
odd transfer ¢ A—8 
purging® 12-19, 12-24 to 12-25 
requesting ® 12-18 
speed ® 12-10 
Direct 1/O® 1-18, 7-4, 14-16, A-39, A-58 
additional buffer regions for® A—41 to A-43 
checking accessibility of process buffer for ¢ 
C-—43 to C—44, C-55 to C-56 
FDT routines for® 7—5, 7-8 
locking a process buffer for¢C—31 to C-33, 
C-34 to C-36, C-40to C—42, 
C-45 to C-47, C-53 to C-54, 
C-—57 to C-58 
postprocessing ® C—70 
reasons for using® 1-18, 6-7 
unlocking process buffer * C—105 
Direct memory access transfer 
See DMA transfer 
Directory sequence number ® A-61, A-62 
Direct-vector interrupt® 12—2, 12—28, 12-30, 
12-32, 16-9, A-7, A-8, A-23, B-3 
Disk driver® 7-8, 8-3, 8-6, 9-5, A-57, A-58 
See also MBA, MASSBUS 
ECC correction routine for * C—65 
pack acknowledgment in® 11—2 
recording disk geometry in® 11-2 
removing a disk volume in® 9-8 
using local disk UCB extension ® A—48, 
A-61 to A-62 
waiting for disk unit spinup in® 11-2 
DLDRIVER.MAR®E—1 to E-29 
DMA transfer® 1-17 to 1-18, 5—5 
See also Map registers, Data path 
byte-aligned® 12—11 
calculating starting address® 12-26 to 12-27 
detecting memory error during ® 12—25 
flow*® 1-19 to 1-21, 12-8 
for modify operation® C—31 to C-—33, 
C-~—34 to C-36 
for read operation® C—40 to C—42, 
C-—45 to C-—47 
for write operation ® C—53 to C-—54, 
C-57 to C-58 
longword-aligned 32-bit random-access ® 
12-12, 12-14 - 
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DMA transfer (cont’d.) 
on MicroVAX |¢ 12-24 to 12-25, 
12-26 to 12-27 
on Q22 bus® 12-15 to 12-16, 
12-19 to 12-26 
on UNIBUS® 12-15 to 12-26 
on VAXBI bus® 14-15 to 14-19 
postprocessing ® 12-16, 12-24 to 12-26 
start I/O routine® 8-1 to 8-7 
using direct data path ine 12—10 
using direct 1/O ine 6—7 
using 1/O adapter resources in®12~—2 to 12-14 
DMB32 asynchronous/synchronous multiplexer ® 
14-17 
DPT$V_NOUNLOAD ® 15-7 
DPT$V_SMPMOD e 15-10, G-3 
DPT$V_SUBCNTRL ® 13-14 
DPT$V_SVPe A-58, B-19, C-77, C-78 
DPT$W_DEFUNITS ¢ 15-18 
DPT$W_DELIVER e 15-18, D—19 
DPT$W_UNLOAD ® D-9 
DPT (driver prologue table)® 1-2, 3-5, 11-1, 
16-7, A-30 to A-34, A-53, A-54 
creating ®6—1 to 6-3, B—-19 to B-24 
initialization tablee 6-2, 15-4, A-32, 
B-23 to B—24 
linked into system DPT liste 15-3, 15-7, 15-8 
reinitialization table ® 6-3, 15-4, 15-8, B—24, 
B-24 
DPTAB macro®6—1, 11-1, 14-9, 15-1, A—48, 
B-19 to B21 
controlling autoconfiguration with ® 
15-17 to 15-18 
example * B—21 
used by MASSBUS drivers ® 13-14 
DPT_STORE macro * 3-5, 6-2 to 6-3, 11-9, 
B-22 to B-24 
example ¢ B—2 1 
DR11—W driver®F—-1 to F—25 
Driver 
See Device driver 
Driver dispatch table 
See DDT 
Driver prologue table 
See DPT 
Driver unloading routine* 6-3, 11-4, 14-18, 
15-7 to 15-8, B—20, B-24 
address ° 6-2, A-33, D-—9 
context ® D—9 
exit method ¢ D—9 
functions * D—9 
input ¢ D—9 
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Driver unloading routine (cont’d.) 
register usage ® D—9 
synchronization requirements ¢ D—-9 
DRV11-WA driver®F—1 to F—25 
DSBINT macro ® 3-8, 3-9, 8-5, 8-6, B-25, 
G-—4, G-10 
replacing with spin lock synchronization macro ® 
G-13 
Dual path UCB extension * A—48 
Dual ported device * A-53 
DWBUA (BI-to-UNIBUS adapter)*® 1-12, 14-9, 
18-3 
See also UNIBUS adapter 
DWMBA 
See Memory interconnect to VAXBI adapter 
DYN$C_BUFIO ® C—12, C-22 
DYN$C_IRP © C—12 
Dynamic spin lock * 3-12 
DZ11 controller® A~19 
DZ32 controller® A—19 


E 


ECC error correction® A-57, A-58, A-62, B—-19, 
C-65 
ECC position register ® A-62 
ECRB (Ethernet controller data block) *B—2 
EMB$C_DA ® 11-9 
EMB$C_DE® 11-9 
EMB$C_DT ® 11-9 
EMB$L_DV_REGSAV ® 11-9 
EMB$W_DV_STS e C-91 
$EMBDEF macro ® 11-8 
EMB spin lock ® 3-13, C-8 
Emulated instructions 
in device driver ® 5—3 
ENBINT macro® 3-8, 3-9, B-26, G—4 
replacing with spin lock synchronization macro ® 
G-13 
Encryption key ® A—41 
Entry point 
specifying in driver tables * B—1 1 
$EQULST macro®B-27 to B-28 
example ® B—27, B—71 
ERL$DEVICEATTN® 11-9, C-8 to C-9, D-14 
ERL$SDEVICERR ® 11-9, A-29, A-58, A-60, 
C-8 to C~9, D-14 
ERLSDEVICTMO ® 10-6, 11-9, A-29, A-58, 
A-60, C-8 to C—9, D-14 
ERLSRELEASEMB ¢ 10-3, C-92 





Error 
See also Error logging 
associated with I/O request ® 11-9 
not associated with |/O request ® 11-9 
servicing within driver® 1-3, 8-5, 
C-79 to C-80 
Error log allocation buffer® 11-9, C-8 
Error logging * A-58, C-8 to C-—9 
driver prerequisites ® 11-8 
enabling ® A—53 
error log sequence number ® A—41 
final error count ® 10-3 
inhibiting © C-8 
in progress © A-56 
performed by IOC6REQCOM ® C-92 
Error logging enable bit 
See UCB$V_ERLOGIP 
Error logging routine® 1-4, 11-8 to 11-10, A-29 
See also Register dumping routine 
address ® 11-1 
Error log in progress bit 
See UCB$V_ERLOGIP 
Error log UCB extension *® A-48, A-58 to A-60 
Error message buffer ® 3-13, 10—3, A-60, A-62, 
C-79 
allocating ® 11-9, C-—8 
filling © C-9 
initializing ® 11—9 
releasing ® 10-3, C-92 
size * C-—8 
specifying sizee6—4, 11-9, A-29 
written into by IOCSREQCOM ¢ C-92 
Error status 
clearing ® 11-1 
Event flag ¢ A-38 
handling for aborted I/O request ¢ C—11 
posting © 4—17 
setting ®2—7 
Exception 
generating © 5—4 
EXE$ABORTIO® 7—4, 17-12, A-39, C-7, 
C-10 to C—11, C—33, C-42, C—44, C-46, 
C-49, C-—50, C-54, C-56, C-58, D-11 
EXE$ALLOCBUF ¢ 7-6, 14-16, C-12 to C-—13 
EXESALLOCIRP ® A—41, A—43, C-12 to C-13 
EXE$ALONONPAGED ® C-13, C—14, C-59 
EXE$ ALONPAGVAR ® C-15 
EXE$ALOPHYCNTG ® 12-26, 14-18, C—16 
EXESALTQUEPKT ¢ 7-5, A—29, C-5, C-17, D-2, 
D-11 
EXESASSIGN® 11-11, A-11, D-5 
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EXES$BUFFRQUOTA 

replaced in VMS Version 5.0¢G—5 
EXES$BUFQUOPRC 

replaced in VMS Version 5.0°G—5 
EXE$CANCEL® 11-6 to 11-7, C-66 
EXE$CREDIT_BYTCNT ® 7-7, C—18, G-5 
EXESCREDIT_BYTCNT_BYTLM®C-18, G—5 
EXESDASSGNe A-11 
EXESDEANONPAGED ® C—3, C-13, C-19 
EXE$DEBIT_BYTCNT ®C—20 to C—21, G—5 
EXESDEBIT_BYTCNT_ALO® 7-6, 14-16, 

C-22 to C-23, G-6 
EXES$DEBIT_BYTCNT_BYTLM ® 7-6, 

C-20 to C-21, G—-5 
EXE$SDEBIT_BYTCNT_BYTLM_ALO ® 7-6, 

14-16, C-22 to C-23, G-6 
EXESDEBIT_BYTCNT_BYTLM_NW e 

C-—20 to C-21, G-6 
EXE$DEBIT_BYTCNT_NW ®C-20 to C-21, G-5 
EXESFINISHIO® 7-4, 7-8, 17-12, A-40, 

C-24 to C-25, C-48, C-49, C-—50, D-11 
EXESFINISHIOC ¢ 7-4, A~40, C-24 to C-25, 

D-—11 
EXESFORK® 11-5, A-19, B-30, C-26 
EXESFORKDSPTH ® 3-5, 3-21, A-52 
EXE$GB_CPUTYPE ¢ B-9 
EXE$SGL_ABSTIM® A-—20 
EXE$SGL—CONFREGL ® 14-6 
EXE$GL_INTSTK 

replaced by CPU$L_INTSTK ® A—12 
EXE$GO_1ST_TIME ® 3-7, 3-8, 3-12, 3-13, 

C-29 
EXE$GO_SYSTIME ® 3-7, 3-8, 3-13, B—47, 

C-67 

reading ®G-—15 
EXESHWCLKINT ¢ 3-7 
EXESINSERTIRP ® 4—12, A-38, A-39, A—55, 

C-27, C-28, C-38 
EXE$SINSIOO ¢ 3-20, 4-12, 8-1, A-56, C-28, 

C-38 

returning control to ® 4-14 
EXE$INSIOQC ¢ C-28 
EXESINSTIMQ ¢ C-29 
EXESIOFORK ® 9—4, 10-1 to 10-2, 12-24, 

A-51, A-52, C-30 
EXESMODIFY ¢C-—31 to C-—33 
EXE$MODIFYLOCK ® C-32, C-34 to C-36 
EXESMODIFYLOCKR® A-42, C-32, 

C-34 to C-36, C-105 
EXESONEPARM® 7-8, A-—40, C-—37 
EXE$QIO* 4-1 to 4-12, A-11, A-29, 

A-36 to A-39, A-41 
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EXESQIOACPPKT ¢ A-52 
EXESQIODRVPKT ® 4—12, 7-4, 7-8, 7-9, 8-1, 

C-32, C-37, C-38, C-—41, C-50, C-54, 

C-60, D-11 
EXESQIORETURN® 17-12, C—39 
EXESREAD ¢ 7-8, A-41, C-40 to C-42 
EXESREADCHK ® 7-6, C-43 to C-—44 
EXESREADCHKR ® C-32, C-35, C—41, 

C-43 to C-44, C—45 
EXE$READLOCK ® C-41, C—45 to C-—47 
EXE$SREADLOCKR ® A-42, C—41, C-45 to C-47, 

C-—105 
EXESSENSEMODE ¢ 7-8, C-48 
EXESSETCHAR® 7-8, C-49 to C—50 
EXESSETMODE ¢ 7-8, C-49 to C-—50 
EXESSNDEVMSG ¢ 9-7 to 9-8, 10-6, 

C-51 to C-52, G-—7 
EXESSWTIMINT ¢ 3-7 
EXESTIMEOUT * A-52, A-56, A-57 
EXESWRITE ® 7-8, A-41, C-53 to C-54 
EXESWRITECHK ¢ 7-6, C-55 to C-56 
EXESWRITECHKR e C-54, C-55 to C-56, C-57 
EXESWRITELOCK ® C-54, C-57 to C-58 
EXESWRITELOCKR ¢ A—42, C-54, C-57 to C-58, 

C-—105 
EXESWRTMAILBOX ® C-51, C-59 
EXE$SZEROPARM ® 7-9, A-40, C-—60 
Expected interrupt 

See Device interrupt 
External register base 


See MBA$L_ERB 


F 


FDT (function decision table)® 1-2, 4-9 
address ® 4—7, 6-3, A-29 
as used by EXE$QIO 4-7 
creating ®°6—4 to 6—7, 11-3, B-34 to B-35 
dispatching to FDT routines from * 4—10 
relocating addresses specified in® 11—4 
size ¢* A—30 
specifying buffered functions in® 4—9 
specifying legal functions in® 4—9 

FDT routine® 1-3, 1-18, 2-3 to 2-4 
adjusting process quotas ine C—12 
allocating IRPE ine A—41 
allocating system buffer in® 7-6 to 7-7 
calling sequence ¢ 7-2 
completing an I/O operation ine C—-24 to C-—25 
context ® 4-12, 7-1, D-10 
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FDT routine (cont’d.) 
creating® 7—1 to 7-5 
dispatched to/from EXE$QIO * 4-10 
ensuring an even byte count in® 12-23 
entry point ® D—10 
exit method® 7-2 to 7-4, D-—11 
for buffered |/O® 7-6 to 7-8 
for direct |/O® 7-5, 7-8, C-31 to C-33, 
C-—40 to C-42, C-53 to C-—54 
provided by VMS® 7-8 to 7-9 
register usage ® 5-2, 7-1, D—10 
returning to the system service dispatcher ® 
C-39 
setting attention ASTs in® C-6 
specifying e D—10 
synchronization requirements ® D—10 
unlocking process buffers ine C—105 
File structured device ® A—53 
File system 
synchronizing access to® 3-12 
FILSYS spin lock ® 3-12 
FIND_CPU_DATA macro * B—29, G—7 
example ® B—29 
Floating address ® 15-12 
Floating CSR space 
assigning to device ® 15-19 
current base ® 15—19 
Floating-point instructions 
in device driver © 5—3 
Floating vector space 
assigning to device ® 15-19 
current base ® 15-19 
Fork block® 1-5, 1-8, 3-21, 3-24, 
4-13 to 4-14, 8-7, 10-1, B-72, C-26, 
C-30, C-—101 to C-—102 
dequeuing ® 3-5 
in CRB® 15-7, A-19 
in extended UCB® 11—5 
in UCB® A-51 to A-52 
Fork context ® 1-8, 3-20 to 3-21, 4-13 
Fork database ® 3-5 
accessing ®B-31 to B-32 
synchronizing access to® 3-20 to 3-22 
Fork dispatcher ®2—6, 3-3, 3-5, 3-7, 3-21, 
B-31 
functions ® 4—15 
Forking ® 3-15, 3-21, B-30, B—40, C—26, C-30, 
G-9 
avoiding multiple ® 11-5 
from controller initialization routine ¢ 
11-5 to 11-6, D-7 
from driver unloading routine ¢ D—9 


Forking (cont’d.) 


from interrupt service routine ® 9-5 
from unit initialization routine® 11-5 to 11-6, 
D-21 
in terminal port driver® 17-13, 17-18 
Fork IPL® 2-4, 3-2, 3-5, 3-14, 3-20, 4—15, 
A-51, B-31 to B-32 
Fork locke 2—4, 3-5, 3-7, 3-12, 3-14 to 3-15, 
3-20, 11-6, 12-15, A-—19, A-47 
See also Spin lock 
acquisition IPL®C—107 
multiple acquisition of *B—33, C—111 
obtained by fork dispatcher ® 3—5 
obtaining * 3-9, B—31 to B-32, C—107 
ownership ® 16-26 
rank®3-—12 to 3-13 
releasing ®° 3-9, B—~33, C-109 
restoring ®¢B—33, C—111 
Fork lock index® 3-12 to 3-13, A—51 
list © G-9 
placing in UCB$B_FLCK ¢ 6-2, B-24, G-8 
FORKLOCK macro ¢ 3-8, 3-9, B—31 to B-32, 
C-107, G-4 
example ¢ B—32 
FORK macro® 3-11, 3-21, 12-18, 12-20, B-30, 
C-26 
See also IOFORK macro 
Fork process ® 1-8, 3-20 to 3-22, 8-1 
context®4—12 to 4-13, 4-13 to 4—14, 
4-14, 8-1to 8-2 
creating *° B—30, B—40, C-26, C-30 
creation by driver® 2-6, 4—14, 10-1 to 10-2 
creation by IOC$SINITIATE® 4-12 to 4-13, 
8-1, 10-3, C-68 to C-69 
reactivating® 4—15 to 4-16 
rules © 3-22 
suspending ® 4-14, 8-6 to 8-7, B-72, 
C-101 to C—102 
Fork queue ® 3-22, 4-14, 4-15, A-16, A-51, 
C-—26, C-30, G-15 
FORKUNLOCK macro ® 3-9, B—33, C—109, C—111, 
G-4 
example ¢ B—32 
Full-checking synchronization image ® 16-25, 
G-17 
loading * G—2 
Full duplex device driver® 7-5, D-2 
1/O completion for ® C—5 
FUNCTAB macro® 6-6, B—34 to B-35 
example ¢ B—35 
Function decision table 
See FDT 
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G 


General purpose registers 
rules for using in driver code ® 5-2 

Generic VAXBI device® 11-2, 14—1 to 14-28 
See also VAXBI node 
initialized by driver® 14-9 to 14-15 
initialized by VMS® 14-5 to 14-9 
interrupt destination ® 14-8 


H 


Hardware clock 
See Interval clock 
HWCLK spin lock ® 3-7, 3-8, 3-13, C-29, G—14, 
G-—15, G-25 





|/O adapter® 1-6, 1-10 to 1-16, 1-17 
See also UBA, UNIBUS adapter, MBA, and 022 
bus . 
configuration register ¢ A—6 
data path register * B—46 
displaying nexus value® 15-8, 15-9 
number of address bits ® A-8, B-3 
on VAXBI bus ® 14—2 
type® 14-8, A-6, A-32, B-3, B—-19 
|/O adapter registers 
See Map registers, Data path register, Vector 
register, Byte count register, MBA 
1/O address space® 18-1 to 18-7 
access to during bus power failure ® 18-6 
error in mapping ® 18-6 
mapping to process address space ® 18-4, 
18-5 to 18-7, 18-7 
of VAXBI bus ® 14—2 
rules for referencing ® 18-6 
1/O channel 
See Process |/O channel 
1/O completion 
See |/O postprocessing 
1/O database® 1-4 to 1-6, A-1 
creation®6—1, 6-2, 11-3, 13-6, 
15-3 to 15-6, 15-11, A-32, B-24 
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\/O database (cont'd.) 


examining with XDELTA ® 16-10 
for MASSBUS configuration® 13-6 to 13-7, 
13-12 
for two-controller configuration * 4-6 
initializing ® 11-3, 15-11 
locating ® 15—10 
referencing fields ine 5—1 
reinitializing © 11—4 
1/0 function 
analyzing ® 8—2 
indicating a buffered® 4-9, 6—4 
indicating as legal to a device* 4-9, 6-4 
preprocessing ® 4—10 
1/O function code ® 4-9, A-38 
converting to device-specific function code ® 
8-4 
defined by VMS °6-4 to 6-6 
defining device-specific * 6—7 
1/O function modifier * 4—9 
1/O postprocessing ¢3—4, 10—1 to 10-4, A-—40 
device-dependent® 2-7, 4-17, 7-7, 
10-2 to 10-4 
device-independent ® 2-7, 4-17 to 4-18, 7-7, 
C-—70 to C-71 
for aborted I/O request * C—10 
for buffered |/O® 7-7 to 7-8, 12-25 
for DMA transfer® 12-16, 12—24 to 12-26 
for full duplex device driver ¢C—5 
for 1/O request involving no device activity ® 
C-24 to C-—25 
synchronization flow ® 3-4 
1/O postprocessing queue® 10-3, 11-6, A—16, 
A-57, C—5, C-92, G—15 
1/O preprocessing 
See also SYS$QIO and FDT routine 
completing * 4-12, 6—4 
device-dependent® 2-3 to 2-4, 4-9 to 4-12, 
7-1 to 7-9 
device-independent ® 2-3, 4-1 to 4-9 
IPL requirements ¢ 3—4 
1/O request 
aborting ® 7-4, 10-6, C-10 to C-11 
canceling® 11-6 to 11-8, A-29, A-56, C-—66 
completing * C—91 to C-92 
example ®2—1 to 2-7 
outstanding on channel® A-11 
restarting after power failure * 8—5 
retrying® 10-5 to 10-6 
returning completion status of to process ® 2—7, 
4-18, 7-4, 10-2, 10-3 
status * A-39 
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1/O request (cont’d.) 
synchronizing simultaneous processing of 
multiple® 7-5 
validating device-dependent arguments ® 2—3 
validating device-independent arguments ® 
2-2 to 2-3, 4-7 
with no parameters ® 7-9, C-60 
with one parameter ® 7—8, C-—37 
1/O request packet 
See IRP 
1/O space 
of MASSBUS ¢ 13-4 
of O22 bus® 12-4 
of UNIBUS ¢ 12-4 
rules for referencing °5—3, 5-4 
writing to ® 5—4 
1/O status block 
See IOSB 
IDB$L_ADP ® 4—5 
IDB$L_CSR*e 4-5, 13-4, 13-12, 14-8 
IDB$L_OWNER ® 3-24, 4—4, 4-5, 8-4, 8-7, 
9-3, 11-2, C-83, C-97 
IDB$L_UCBLST ® 14-20 
IDB$V_NO_CSR ® A-35 
IDBSW_UNITS © 14-7, 15-6 
IDB (interrupt dispatch block)® 1-6, 4—5 to 4-6, 
12-23, A-34to A-36 
address ®° 4-4, 8-4, 12-31, 12-33 
creation ® 15—4, B—20 
for generic VAXBI device ® 14—7 
for MBA® 13-4, 13-6 to 13-7, 13-12, 
13-14 
size © B—20 
Idle time * G-24 
IFNORD macro ® B—36 to B-37 
IFNOWRT macro®B—36 to B-37 
IFRD macro ®B-36 to B-37 
example ® B—37 
IFWRT macro ® B—36 to B-37 
ILLQBUSCFG bugcheck ® A—20 
Image termination® 11—6, D-3 
INCONSTATE bugcheck ¢ C—-85, C-94 
INISBRK © 16-6 
Initialization routine 
See Unit initialization routine, Controller 
initialization routine 
Initialization table® 6-2, A-33, B—23 
INIT module ¢ G—23 
INIT processor state ® A-15, G—21 
Input device * A—53 


Interlocked instructions 
using in multiprocessing environment ® 
G-14 to G-15 
Interprocessor interrupt ® 3-4, 3-13, A-15 
Interrupt © 3-2. 
See also Device interrupt 
blocking * B—25, B—60 
dismissing ® 10-1 
interprocessor ® 3—4, 3-13, A-15 
requesting an XDELTA® 16—7 to 16-8 
requesting a software ® 3-9, B-62 
Interrupt context ® 1-8, 9-3 
Interrupt dispatch block 
See IDB 
Interrupt dispatcher® 3—5, 12-24, 14-7, 14-9, 
A-7, A-8 
for MASSBUS ® 13-7, 13-7 to 13-10, 
13-14 to 13-15, D-23 
for Q22 bus® 12-27 to 12-35 
for UNIBUS ® 12—27 to 12-35, A-23 
Interrupt enable bit *8—4 
Interrupt expected bit 
See UCB$V_INT 
interrupt priority level 
See IPL 
Interrupt service routine ® 1-3, 3-3, 3-13, 
9-1 to 9-8, 12-24, A--52 
address * 6—3, 12-33, A-23, B—24, D-12, 
G-5 
context * 9-3, D-12 
entry point® 4—14, D—-12 
example ® 9-6 to 9-8 
exit method *D-13 
for connect to interrupt facility © 18-10, 
18-16 to 18-17 
for LP11 printer ® 2-6 
for MASSBUS device ® 13-10, 13-15, D-12 
for solicited interrupt® 9-3 to 9-4 
for terminal port driver ® 17-16 
for unsolicited interrupt ® 9-4 to 9-8, D-23 
functions ®°4—14, 9-1, D-13 
input ®*D-—13 
of CONINTERR.EXE ® 18—13 
of UNIBUS adapter ® 12-30 
preemption of device timeout handling ® 10—5 
register usage ®8—7, D—12 
specifying more than one® D-—12 
synchronization requirements® 3-5, 3-19, 
9-3, D-12, G-11 to G—12 
Interrupt stack ¢ 8-1 
address ® A—15 
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Interrupt transfer routine * 12-32 
Interrupt transfer vector 

See VEC 
Interrupt vector ® 15-9 

See Device interrupt vector 

number ® 15—6 
Interval clock © 3-6, 3-7, 3-13, G-25 to G-—26 

interrupt service routine ® 3-7, 3—8 

role in device timeouts ® 1—3 
INVALIDATE spin lock ¢ 3-13 
INVALIDATE_TB macro ® B-38 to B-39, G—16 
INVALID macro 

replaced by INVALIDATE_TB macro ® G—16 
lO$V_INHERLOG ® C-8 
IOS_AVAILABLE function * 7-8 
IO$_CONINTREAD function® 18-8, 18-9 
IOS_CONINTWRITE function® 18-8, 18-9 
lOS_PACKACK function ® 7-8 
lO$_SENSECHAR function 

servicing * C—48 
lIO$__SENSEMODE function 

servicing ® C—48 
lO$__SETCHAR function ® 11—9 

servicing ®°C—49 to C—50 
lOS_SETMODE function ® 17—13 

servicing ® C—49 to C-—50 
1O$_TTY_PORT function ® 17-12 
lO$_UNLOAD function ¢ 7-8 
$IO650DEF macro ® 18—1 
$10730DEF macro® 18-1 
$1IO750DEF macro® 18—1 
$1O0780DEF macro® 18-1 
$IO79ODEF macro® 18-1 
$IO8NNDEF macro® 14-14, 18-1 
$IO8PSDEF macro ® 14—14 
$IO8SSDEF macro® 14-14, 18-1 
$IOOCCDEF macro® 14-14, 18-1 
lIOCS$ALLOSPT 

replaced by LDRSALLOC_PT ¢ G—7 
IOCSALOALTMAP ¢ A-9, C—61 to C-—62, C-90 
lIOCSALOALTMAPN ® 12-20, C-61 to C-—62 
IOC$ALOALTMAPSP ¢ C-61 to C-—62 
IOCSALOUBAMAP ® C-63 to C-64, C-87, C-96 
IOCSALOUBAMAPN ® 12~—20, C-63 to C-—64 
IOCSAPPLYECC ® A-62, C-—65 
IOCSCANCELIO ® 11-8, A-56, C-66, D-3 
lIOC$DIAGBUFILL *® A-29, A-—41, C-67 
lOC$GL_CRBTMOUT # A-20 
lIOC$GL_DEVLIST ¢ 11-4, A-25 
lIOC$GL_DPTLIST ¢ 15-3, 15-8 
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lOC$GL_IRPFL 
replaced in VMS Version 5.0®G—-15 
lOC$GL_LRPFL 
replaced in VMS Version 5.0°G—15 
lIOC$GL_MUTEX ¢ 11-11, D—-5 
lOC$GL_PSFL 
replaced by CPU$L__PSFL®* G—15 
lOC$GL_SRPFL 
replaced in VMS Version 5.0°G—15 
lOC$GO _IRPIO * G—15 
jIOC$GOQ_LRPIO e G-15 
lOC$GQ__SRPIO * G-15 
lIOCS$GW_MAXBUF ® C~—20, C—22 
IOCSINITIATE © 3-20, 4-12 to 4-13, 8-1, 10-3, 
A-29, A—40, A—55, A-56, A-58, C-28, 
C-38, C-67, C-68 to C-—69, C-92, D-15 
IOC$IOPOST ¢ 3-4, A—41, A-42, C-70 to C-71 
unlocking process buffers © C—105 
IOCSLOADALTMAP ® 12-22, B—41, 
C-72 to C-73 
IOC6LOADMBAMAP ® 13-3, B—42, C—74 
lIOCSLOADUBAMAP ® 12-21 to 12-22, A-24, 
B-43, C-75 to C-76 
IOC6LOADUBAMAPA ® 12-22, C—75 to C—76 
IOCSMNTVER ® A—29 
lIOCSMOVFRUSER ® 12-26, 14-18, B—-19, C—77 
IOCSMOVFRUSER2 ®¢ C—77 
lIOCSMOVTOUSER ® 12-27, 14-19, B—19, C-78 
lIOCSMOVTOUSER2 ® C-78 
IOCSPURGDATAP ® 12-24 to 12-25, 12-27, 
A-24, B—46, C-79 to C-—80 
IOCSRELALTMAP ® 12-26, A-9, A-52, B-48, 
C-81 to C-82 
IOCSRELCHAN ® 10-2, A-19, A-35, A-52, 
B-49, C-83, C-92 
called by IOC$WFIRLCH ¢ C—102 
IOCSRELDATAP ¢ 12—25, A-7, A-9, A-52, B-50, 
C-84 
IOCSRELMAPREG ® 12-25 to 12-26, A-8, A-9, 
A-24, A-25, A-52, B-51, C-86 to C-—87 
lIOCS$RELSCHAN ® A-19, A—20, A-35, B-52, 
C-88 
IOC6REQALTMAP ¢ 12-19, A-9, A-52, B-53, 
C~89 to C-90 
lIOCSREQCOM ¢ 3-20, 8-1, 10-3 to 10-4, 
A-29, A-38, A-40, A-55, A-—-56, A-57, 
A-58, A-60, B—54, C-13, C-91 to C-92, 
D-15 
error logging activities © 11—9 
lIOCSREQDATAP ® 12-17, A-7, A-9, A-24, 
A-52, B—55, C-93 to C-94 
IOCSREQDATAPNW ® 12-18, C-93 to C-94 
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IOCSREQMAPREG ® 12-19, A-8, A-9, A—24, 
A-25, A-52, B—56, C-95 to C-—96 

IOCSREQPCHANH ® A-19, A-35, A—52, B-57, 
C-97 to C-98 

IOCS$REQPCHANL® 8-3 to 8-4, A-19, A-35, 
A-52, B-57, C-97 to C-98 

IOCSREQSCHANH ¢ A-19, A-20, A-35, B-58, 
C-97 to C-98 

IOCSREQSCHANL ® A—19, A—20, A-35, A-52, 
B-58, C-97 to C-98 

IOCSRETURN® 11-7, B—11, C-99 

IOCS$SEARCHDEV ®¢ A-52 

IOC$VERIFYCHAN ®¢ C—100 

IOCSWFIKPCH © 4-13, 4-14, 8-7, A-52, A—-56, 
A-57, C-101 to C-—102 

IOCSWFIRLCH ® 4-13, 4-14, A-56, A-57, 
C-101 to C-—102 

$IODEF macro ® 6—4 

IOFORK macro ® 3—11, 3-21, 4-14, 9-4, 10-1, 
12-24, B—40, C-30 

IOLOCK 10 fork lock * 3-12 

IOLOCK 11 fork lock ¢ 3-13 

IOLOCK8 fork lock ® 3-7, 3-12 

IOLOCK®Y fork lock ® 3-12 

IOSB (I/O status block) * 7—4, 10-2, 10-3, A-39, 
A-40, C-5, C—10, C-71, C-92 

validating access to ® 4—7 

$lIOUV 1DEF macro® 18-1 

$IOUV2DEF macro ® 18—1 

IPL$_ASTDEL ® 3-2, 3-4, 3-16, 4—7, C-10, 
C-12, C-31, C-34, C-37, C-38, C—40, 
C-43, C—-48, C-49, C-55, C-60, C-71, 
C-100, C-109, C-111, C—112, D-5, D-10 

IPL$6_EMB ¢ C-8 

IPL$_FILSYS ¢ 3-12 

IPL$_IOLOCK8 ® 3—12 

IPL$6_IOPOST ¢ 2-7, 3-2, 3-4, 4-17, 10-3, 
11-6, C-5, C-10, C-24, C—71, C-92 

IPL$_JIB * 3-12 

IPL$_MAILBOX ® 3-2, 3-8, 3-13, 9-7, 10-6, 
C-51, C-59 

IPL$_MMG e 3-12 

IPL$_POOL e 3-2, C-14, C-15 

IPLS$_POWER ® 3-6, 8-5 to 8-6, 11-4, 15-4, 
D-7, D-9 

IPL$_QUEUEAST ® 3-2, 3-7, 3-12, 18-15, 
18-17, C-2, C-3 

IPL$_.RESCHED ® 3-2, 3-5, 3-7, B—29, C—107, 
C-108 

IPL$_SCHED ® 3-12 

IPL$¢_SYNCH ¢ 3-2, 3-7, 3-8 

IPL$_TIMER ¢ 3-12, C-29 


~ IPL$_TIMERFORK ® 3-2, 3-7, 10-4 


IPL (interrupt priority level)® 1-7, 3-1 to 3-11 
See also Device IPL, Fork IPL 
hardware ® 3-1 
lowering®3—8 to 3-11, 3-21, 8-7, C-26, 
C-30 
modifying¢B-15 to B—16, B-17 to B-18, 
B-25, B-26, B-31 to B-32, B-33, 
B-44 to B-—45, B-60, B-66 
raising® 3-8 to 3-11, 3-14, B-60 
relation to spin lock ® 3-13 
saving ® 3-9, B—15, B—-31, B—44, B—59 
software ® 3—1 
IRP$B_CARCON ® A—41, C-32, C-41, C-54 
IRP$B_PRI ® C-27 
IRP$L_BCNT 8-2, C-32, C-—35, C-41, C-43, 
C-45, C-54, C-55, C-—57, C-68, C-69, 
C-70 
writing ® 7—6 
IRP$L__DIAGBUF ¢ C-67, C-68, C-69 
IRP$L_IOST2 ¢ C-32, C-41, C-54 
IRP$L_KEYDESC ® C—70 
IRP$L_MEDIA ® 7—4, 10-3, 11-6, A—40, C-37, 
C-50, C-60 | 
IRP$L_PID® 11-8, C-66, D-4 
IRP$L_SVAPTE ® 8-2, C—32, C-35, C-41, C-46, 
C-54, C-58, C-68, C-69 
for buffered |1/O* 7-6, 7-7 
IRP$V_BUFIO e C-70 
IRP$V_DIAGBUF ¢ C-67, C-68, C-69, C—70 
IRP$V_EXTEND ¢ C-70 
IRP$V_FUNC e 7-6, 7-7, 11-6, C—32, C-35, 
C-—41, C—43, C-46 
IRP$V_KEY ®C—70 
IRP$V_MBXIO ® C—70 
IRP$V_PHYSIO * C-—70 
IRP$W_BOFF® 7-6, 7-7, 8-2, C-32, C-35, 
C-—41, C-46, C-54, C-58, C-68, C-69, 
C-70 
IRP$W_CHAN® 11-8, C-66, D-4 
IRP$W_FUNC ¢ 8—4 
IRPS$W_STS 
for read function® 7-6, 7-7 
for write function ® 7—7 
IRP (I/O request packet) ® 1-6, A-36 to A-41 
allocating ® 4—7 
copying to UCB ® 8-2 
creation ® 2—3, 4-7 
current ® A—55 
deallocation ® 2—7, C-71 
dequeuing from UCB * A~38 
device-independent portion of * 4—8 


Index 


IRP (I/O request packet) (cont’d.) 
insertion in pending-I/O queue® 2-4, 4-12, 
7-4, 8-1, C-27, C-28 
insertion in postprocessing queue ® 2—7 
removal from pending-I|/O queue*2—7, 4-12, 
10-3 
size © A-36 
storing data ine 5-1, G-16 
unlocking buffers specified ine C-—105 
IRPE (1/O request packet extension) * A—-39, 
A-41 to A-43, C—70 
address ® A—41 
allocating © A—41 
deallocation ® A—42, C-71, C-—105 
unlocking buffers specified ine C—71, C-—105 


J 


JIB$L__BYTCNT ° 3-12, 7-6, 7-7, C-12, C—18, 
C-20, C-22, G-5 
JIB$L__BYTLM ® 3-12, C-12, C-18, C-20, C—22, 
G-5 
JIB$V_BY TCNT_WAITERS ® C—18 
JIB (job information block) ® 3-12 
JIB spin lock ¢3—12, C-18, C-20, C-22 
Job attached bit 
See UCB$V_JOB 
Job controller ¢ A—57 
sending a message to®9-7 to 9-8, C-52, 
C-59 
Job information block 
See JIB 
Job quota ¢ G—5 
byte count® 2-3, 3-12, C-12, C—18, 
C-20 to C-21, C-22 to C-—23 
byte limite 3-12, C-12, C-—18, C-20 to C-21, 
C-22 to C-23 








K 


Kernel stack ®¢ 8—1 


L 


LDRSALLOC_PT ¢ 14-15, C-103, G-7 
LDRSDEALLOC_PT *C-—104 
LDR$GL_FREE_PT ¢C-—103, C-104 
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LDR$GL_SPTBASE ® C—103, C—104 
Legal function bit mask ® 4—9 
LOADALT macro® 12—10, 12-22, B—41, C-—72 
LOADER$_PTE_NOT_EMPTY status *C—104 
LOADMBA macro ® 13-3, 13-12, 13-13, B—42, 
C-74 
LOADUBA macro® 12-10, 12-11, 12-21, B—43, 
C-75 
Local disk UCB extension® A~48, A-61 to A-62 
required for error logging® 11-8, C-—9 
required for IOCGAPPLYECC routine * C-65 
Local processor ® 1—7 
Local tape UCB extension® A-48, A-60 to A-61 
required for error logging® 11-8, C-—9 
Lock IDe A—52 
LOCK macro ® 3-8, 3-9, B—44 to B—45, C-107, 
G-—4 
Lock manager *® A~52 
Logical 1/O function 
translation from virtual function to *2—3 
‘translation to physical function®C—31, C—40, 
C-53 
Longword access enable bit 
See VEC$V_LWAE 
Longword-aligned random-access mode ® 12-2, 
12-11, 12-14, A~24 
Lookaside list 
See Nonpaged pool 
Loopback mode ® A-69 
LWAE (longword access enable) bit 


See VEC$V_LWAE 


M 


Machine check ®3—13, 16-21, 18-6 
condition handler ® 18-6 
Machine check protection block ¢ 14—1 1 
Macro 
format ® B—1 
Mailbox ® A—53, A—54, A-55 
associated with device ® A—56 
buffered I/O quota for® A-52 
1/O function * A—39 
in shared memory ® A-57 
marked for deletion ® A—57 
of job controller ® 9-7, G—7 
of OPCOM process ® 10-6, G—7 
permanent ® A—57 
sending a message to®C—51 to C—52, C-59 
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Mailbox (cont'd.) 

synchronizing access to® 3-8, 3-13 
Mailbox driver ® 15—5 
MAILBOX spin lock *3—13, C-51, C-59 


_ Maintenance function® 17—13 


Map register base register 
See MBA$L_MAP 
Map registers® 1-17, 12-2, 12-4 to 12-7, 
12-15, 12-19 to 12-22, A-8, 
A-23 to A-24, A-24, B-3 
See also Alternate map registers 
alloceting ®*C—63 to C—64 
allocating permanent® 11—2, 12—20 to 12-21, 
A-24, G-12 
byte offset bite C—75 
calculating the number needed ® 12-19 
format® 12-5 to 12-7, 12-21 
invalidating ® 12—7, 12-13, 12-22 
loading® 12-21 to 12-22, B-—43, 
C—75 to C-76 
number of active ® A—9 
number of disabled * A—9 
of MBA® 13-2, B—42, C-—74 
of Q22 bus® 12-5 
of UBA® 12-5 
operation® 12—5 to 12-7 
releasing ® 10-2, 12-25 to 12-26, B-51, 
C-86 to C-87 
requesting® 12-19 to 12-21, B-—56, 
C-95 to C-96 
Map register valid bite 12-21 
Map register wait queue ® 12-19, 12-25, A-8, 
C-87, C-96, G-14 
MASSBUS 
configuration ® 13-1, 13-4 
1/O address space ® 18—1 
1/O database *® 13-4, 13-6 to 13-7 
servicing multiunit controller on® 13-2, 13-6, 
13-11, 13-12, 13-14 
servicing single-unit controller on® 13-6, 
13-10, 13-11, 13-12, 13-14 
MASSBUS adapter 
See MBA 
MASSBUS driver 
DPT for® 13-14 
interrupt service routine ® 13-15 
start |/O routine ® 13-12 
unit initialization routine ® 13-11 
unsolicited interrupt service routine ® 13—14 
MBASINT ¢ 13-14 to 13-15, D-—23 
MBA$L_AS ® 13-4, 13-5, 13-8 to 13-9, 13-9, 
13-10 


MBA$L_BCRe 13-3, 13-4, 13-13, C-74 
MBA$L_CAR ® 13-4 
MBA$L_CRe 13-4 
MBA$L_CSR® 13-4, 13-13 
MBA$L_DR ® 13-4 
MBA$L_ERB ® 13-4, 13-5, 13-11 
-MBA$L_MAP ® 13-4, C—74 
MBA$L_SMR ® 13-4 
MBA$L_SRe 13—4, 13-10, 13-12 
MBA$L_VAR® 13-3, 13-4, 13-13, C-74 
MBA (MASSBUS adapter) ® 1—10, 1-11 
address space ® 13-4 to 13-5 
data paths 13-3 
functions ® 13-1, 13-8 to 13-9 
nexus value of ® 15—5 
obtaining ownership ® 13-2, 13-6 to 13-10, 
13-12 to 13-13 
registers® 13-1 to 13-6 
device* 13-5, 13-11, 13-12 
external ® 13-2 
internal® 13-2 
map® 13-2 to 13-6, B-—42, C—74 
releasing secondary data channel * C—88 
_ subunit number ® 13-1 
unit number ® 13-1, 13-11, 15-6 
$MBADEF macro® 13-4 to 13-5 
MCHECK spin lock * 3-13 
$MCHKDEF macro® 14—11 
Media ID® A-58 
MEGA spin lock ¢ 3-13 
Memory 
See also Buffer, Nonpaged pool 
detecting corruption in® 16-22 to 16-24 
detecting parity errors in® 12—25, B—46 
testing accessibility of eB—36 to B-37 
Memory interconnect to VAXBI adapter ® 14-2, 
14-6, 14-8 
ADP address ® 14-8 
Memory management resources 
synchronizing access to® 3-12 
MicroVAX 3600 series ® 1-15 
booting with XDELTA from ® 16—2 
requesting an XDELTA interrupt from ® 16-8 
MicroVAX |e 1-16 
accomplishing a DMA transfer on® 
12-24 to 12-25 
adapter logic® 12-1 
booting with XDELTA from ® 16—2 
comparison with other VAX systems ® 1-18 
DMA transfer® 12-26 to 12-27 
requesting an XDELTA interrupt from ® 16-8 


Index 


MicroVAX lle 1-15 
adapter logic ® 12—1 
booting with XDELTA frome 16-2 
requesting an XDELTA interrupt from ® 16—8 
MMG$GL__SBICONF © 14—6 
MMGS$IOLOCK ® C-32, C-35, C—41, C-46, C-54, 
C-—58 
MMG$UNLOCK ¢ A—42, C-105 
MMG spin lock ® 3-12, C-16, C-103, C—104, 
C-—105 
Modem signals 
input transitions of © 17-14 
sending to device ® 17—12 
Mount verification ® A-39, A—57 
Mount verification routine® A-29, A-30 
MSG$_CRUNSOLIC ¢ 9-7 
MSG$_DEVOFFLIN © 10-6 
Multilevel device interrupt dispatching ® 12-32, 
12-34 to 12-36, A-20 
Multiprocessing device driver 
analyzing crash dumps *® G—18 to G—19 
incompatibility with uniprocessing driver e 
15-10, G-3 
using XDELTA® 16-7, G—20 
writing ® G—8 to G—20 
Multiprocessing environment 
contrasted with uniprocessing environment ® 
3-10, G-1 
debugging a driver designed for® 
16-25 to 16-27 
MULTIPROCESSING parameter ® 16-24, 16-25, 
G-2 to G-3, G-—4, G-23 
Multiprocessor state ® A—15, G-20 to G—24 
Mutex 
for ACL® A—45 
for 1/O database ® D—5 
1/O database ® 11-11 


N 


NBI 
See Memory interconnect to VAXBI adapter 
Network device * A—53 
Nexus ® 15-5, 15-8, 15-9 
Nexus ID® A-6 
Node ® 15-5, 15-8, 15-9 
See VAXBI node 
Node ID® 14-8, A—6 
Node private space ® 14—5 
Node space ® 14—5 
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Node space (cont’d.) 
accessing BIIC registers within® 14—5 
address ® 14-8 
mapped by VMS ¢ 14-6 
Non-direct-vector interrupt® 12-2, 12-29, 
12-30, 12-32, 16-8, A-7, A-23 
Nonpaged pool 
allocating® C-12 to C-13, C-—14, C-15, 
C-—22 to C-23 
allocating in initialization routine ® 11—2 
deallocating * C~3, C-19 
lookaside list® C-13, C-14, G-15 
synchronizing access to® 3-13 
variable region® C-15, G—-14 
NPR (Nonprocessor request) 
See DMA transfer 
Null process ® G-24 


O 


Object 
protection ® A—45 
Online bit 
See UCB$V_ONLINE 
Online condition 
on MASSBUS ¢ 13-9 
OPCOM process 
sending a message to® 10-6, C—52, C-59 
Operator device * A—53 
ORB (object rights block) * A—43 to A—45 
address ® A—52 
cloned® 11-12, D-6 
Output device ¢ A~-53 


Page fault 

taken within driver code * 3-4 
Page table 

physical address of ®* 14-18 
Page-table entry 

allocating * C—103 

deallocating * C—-104 

format ® 14—17 

modifying ® B—38, G—16 
Paging |/O function * A—39 


PATSA_NONPGD ¢ 16-20 
Patch space ® 16—20 
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PBI 
See Memory interconnect to VAXBI adapter 
PCB$L_ASTOFL ® G—14 
PCB$L_JIB © 7-6 
PCB$L_PID® 11-8, C-66, D-4 
PCB$V_SSRWAIT ¢ 4-7, C—12, C—20, C-22 
PCB$W_ASTCNT ®C-4, C-6, C-10 
modifying with ADAWI instruction ¢ G— 14 
PCB$W_BIOCNT ¢ 2-7 
PCB (process control block)*3-—4, 16-13 
referring to current ® G—7 
synchronizing access to® 3-12 
PDT (port descriptor table) * A—58 
Pending-I/O queue * 3-20, 4—12, 8-1, 11-6, 
A-38, A-55, C-—27, C—28, C-—37, C-38, 
C-—71, C-92, G—14 
bypassing ® 7—5, C—17 
lengthe A-57, C-28 
synchronizing with driver internal queue * 7—5 
Per-CPU database 
See CPU 
PERFMON spin lock ® 3-13 
Performance 
stack time ® A—16 
PFN database . 
examining with XDELTA® 16-13 to 16—14 
PFN mapping® 18-5 to 18-7 
deleting a page designated for ® 18-6 
modifying a page designated for ® 18-5 
PHD$L_BIOCNT * 2-7 
Physical address 
format ® 18-4 
Physical I/O function ® A-39, C—70 
PID (process identification number) ® A—52 
PIO transfer ® 1-17 
example ® 2-1 to 2-7 
using buffered I/O in®6—7 
using I/O adapter resources in® 12-2 
Pool checking mechanism ® 16-22 to 16-24 
POOLCHECK parameter ® 16-22 
POOL spin lock 3-13, C—14, C-15, C-19 
Port driver 
See Terminal port driver 
Port driver entry vector table © A—33 
Port driver vector table® 17-4, A-67 
address ® 17-8, B—7 
creating® 17-5 to. 17-6, B-68, B-69 
defining entry in® B—67 
relocating ® B—6 
PORT_ABORT service routine ® 17-15 
PORT_CANCEL service routine ® 17—15 


PORT_DISCONNECT initiate routine ® 17-12 
PORT_DS_SET initiate routine ® 17-12 
PORT_FDT initiate routine ® 17—12 
PORT_FORKRET initiate routine® 17-13, 17-18 
PORT_MAINT initiate routine ® 17-13, A-68 
PORT_RESUME service routine ® 17-15 
PORT_SET_LINE initiate routine ® 17-13 
PORT_SET_MODEM initiate routine ® 17-14 
PORT_STARTIO initiate routine ® 17-14 
PORT_STOP service routine ® 17-15 
PORT_XOFF service routine ® 17—16 
PORT_XON service routine ® 17—16 
Position independent code ® 5—1 
Postprocessing 

See |/O postprocessing 
Power bit 

See UCB$V_POWER 
Power failure 

blocking * 3-6 

determining the occurrence of ¢ 8—5 

occurring when device is busy ® A-56 

on |/O bus® 18-6 

servicing in an initialization routine ® 11-1, 11-5 

servicing in port driver unit initialization routine ® 

17-11, 17—20 
Power failure recovery procedure ® A~23, A-24, 
A-52 

device timeout forced by ® 10-5 

initialization performed by® 11-4 to 11-5 
PR$_ASTLVL processor register ¢ 3-4 
PR$_SID processor register ® A-16 
PR$S_SIRR processor register ® 3-8, B-62 
PR$_TBIA processor register * G—16 
PR$_TBIS processor register ®° G—16 
Prefetch function of UNIBUS adapter ® 12-3, 

12-12, 12-13 

Preprocessing 

See |/O preprocessing 
Preprocessing routine 

See FDT routine 
Primary bootstrap program (VMB) * G—22 
Primary processor ® G—2, G—22, G-25 
Printer driver 

description® 2—1 to 2-7 
Process 

See also Process quota 

current ® A-14 

privilege mask ¢ A—41 

quantum end event ® 3-7 

returning control from driver to* 4—14 

scheduling * G-24 


Index 


Process context® 1-7, 2-4, 4-12, 7-1 
returning to® 4—18 

Process I/O channele 11-6, A-—11, A-39 
assigning ® 4—3 
assigning to template device ® 11—11 
deassigning® 11-6, 11-7, 17-12, D—3 
reference count ® A-55, A-56 
validating ® 2-3, 4-4, C-—100 

Processor state 
See Multiprocessor state 

Processor status longword 
See PSL 

Processor subtype ® B—8 

Processor type *B—-8 

Process quota 
adjusting © 4—17 
buffered |/O® 2-3, 2-7, 4-7 
byte count ® 7—7 
charging ®4—7, 4-10, A-40, D—15 
direct |/O¢ 4—7 

Programmed |/O 
See PIO transfer 

$PRTCTEND macro ® 14-11 

$SPRTCTINI macro® 14—11 

PSL (processor status longword) 
examining with XDELTA ® 16—10 
Z condition code * C-27 

PURDPR macro® 12-24, B—46, C-—-79 
detecting memory errors using ® 12—25 


Q 


Q22 bus® 1-15, B-3 
accomplishing a DMA transfer on® 
12-15 to 12-16, 12-19to 12-26 
address size ® 12—5 
device interrupt dispatching ® 12-34 to 12-36, 
A-20 
example of driver designed for®E—1 to E-29, 
F~1 to F-25 
1/O address space *® 18-1, 18-3, 18-6 
|/O space® 12-4 
power failure * 18-6 
rules for configuring® 1-15, 12-35 to 12-36 
scatter-gather map® 12-4 to 12-7 
Q22 bus interface 
functions® 12-1 to 12-14 
obtaining resources of ® 12—15 
QBUS_MULT_INTR parameter ® 12-34 
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Quantum end event ® 3—7 
QUEUEAST spin lock ® 3—12, C—7 
Queue operations 
in multiprocessing environment ® G—14 to G—15 
Quota 
See Process quota, Job quota 


R 


Random access device * A-53 
Rank 
of spin lock * 3-14 
Read check 
enabling ¢ A-53 
Read function * A-39, A—40 
FDT routine for ® 7-8 
postprocessing for® C—70 
READ_SYSTIME macro ¢ B—47, G—15 
example ® B—47 
Real time device ® A-53, A-54 
REALTIME_SPTS parameter ® 18-8 
Record oriented device ® A-53 
Reentrant code ® 5~—1 
Register dumping routine ® 1-4, 11-9, 11-10, 
A-29, A-62, B—46, C-9, C-67, C-79 
address ® 6-3, D-14 
context ® D—14 
entry point *D-14 
exit method ® D—-14 
for generic VAXBI device ® 14—19 
functions ¢ D~14 
input ¢ D—14 
register usage * D—-14 
synchronization requirements ® D—-14 
Registers 
See BIIC registers, Device registers, General 
purpose registers, Map registers 
REI instruction . 
role in AST delivery ® 3-4 
Reinitialization table® 6-2, 15-8, A-33, B-24 
RELALT macro® 12~—26, B—48, C-81 
RELCHAN macro ® 10-2, 13~14, B—49, C-83 
RELDPR macro ® 12—25, B-50, C-84 
RELMPR macro ® 12—25, B~51, C-86 
RELSCHAN macro ®¢ B-52, C—-88 
Remote terminal UCB extension ® A-54 
REQALT macro® 12—10, 12-19, C-89 
REQCOM macro ® 10-3, B-54, C-91 
required for error logging ® 11-9 
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REQDPR macro® 12-11, 12-17, B-55, C-93 
REOQMPR macro® 12-10, 12-11, 12-19, B—56, 
C-95 
REQPCHAN macro * 3-24, 8-3 to 8-4, 13-6, 
13-~12, B—57, C-97 
REQSCHAN macro® 13-6, 13-13, B—58, C-—97 
Resource wait flag 
See PCB$V_SSRWAIT 
Resource wait mode ® 4—7, C-12, C-20, C-22 
Resource wait queue ® 3—23 to 3-24, G—14 
See also Alternate map register wait queue, 
Device controller data channel wait queue 
See also Map register wait queue, Secondary 
data channel wait queue, Data path wait 
queue 
buffered data path ® C—85 
Retry count® 10-6 © 
RLO1 driver¢E-1 to E-29 
RLO2 drivereE—1 to E-29 
RL11 driver®E—1 to E-29 
RSB instruction ® 7-3 
RUN processor state ® A-15, G-21 


S 


SAVIPL macro ® 3-9, B—59 
SBI (synchronous backplane interconnect) ® 1—10 
UNIBUS interlock sequence to® 12—10 
SBICONF array © 14-6 
Scatter-gather map ® 12-4 
See also Map registers 
SCB (system control block)® 14-9, A-—7 
of VAX 6200 series * 14—9 
of VAX 8200/8250/8300/8350¢ 14-9 
of VAX 8550/8700/8800/8830/8840 « 14-9 
SCH$GL__COMOS ® G-24 
SCH$GL_—_CURPCB 
replaced in VMS Version 5.0° G—7 





~“SCH$GL_PCBVEC ® 16-13 


SCH$POSTEF ¢ A-38 
SCHS$QAST ® 3-4 
SCH$SRESCHED *® 3-7 
SCHED spin lock ® 3-4, 3—7, 3-12, C-19, G-24 
Scheduler ¢ G—24 
blocking activity of © 3—5 
synchronization of ¢ 3—7 
SCS (system communications services) ® A—32 
SDA 
See System Dump Analyzer 


SDA current process ® G—19 
$SECDEF macro® 18-6 
Secondary bootstrap program (SYSBOOT) @ 
16-20, G-23 
Secondary controller data channel® 13-12, 
13-14, B—52 
obtaining ownership of *B—58, C—97 to C-98 
releasing © C—88 
Secondary controller data channel wait queue ® 
C-88, C-98 
Secondary processor ® G—21 
Seek operation ® 8-6 
overlapping with data transfer ¢ 8-3 
Selected map register 
See MBA$L_SMR 
Self-test status © 14-23 
Sense device characteristics function ® 7-8 
Sense device mode function ® 7-8 
Set device characteristics function® 7-8, A—54, 
A-55 
Set device mode function ® 7-8, A-54, A—55 
SETIPL macro ® 3-8, 3-9, B-60, G-—4 
example ® B—6 1 
replacing with spin lock synchronization macro 
G-13 
Set mode function ® A—55 
SET PROCESS command ¢ G-—18 
Shareable device * A-53 
SHOW DEVICE command * A-58 
SHOW SPINLOCKS command ® G—17 
SIRR (software interrupt request register) * 3-8 
SMP$ACONOIPL® 16-25, B—15, G-18 
SMP$ACQUIRE © 16-25, B-32, B—44, G-18 
SMP$ACQUIREL © 16-25, B—15, G-18 
SMP$AR_IPLVEC ¢ B-31, C-26, C-—30 
SMP$AR_SPNLKVEC ¢ 3-12, A—46, B-32, B-44, 
B-66 
SMP$GL_FLAGS ¢ 15-10, G-3 
SMP$RELEASE ¢ 16-25, B-33, B-66, G-18 
SMP$RELEASEL ® 16-25, B—17, G-18 
SMP$RESTORE ® 16-25, 16-26, B—-33, B—66, 
G-18 
SMP$RESTOREL ® 16-25, 16-26, B—17, G-18 
SMP$SETUP_CPU © G—23 
SMP$SETUP_SMP ¢ G—23 
SMP$V_UNMOD_DRIVER ¢ 15-10, G-3 
SMP_CPUS parameter ® G-21, G—23 
SOFTINT macro * 3-9, B-62, C-—26, C-—30 
Software timer® G—25 to G—26 
Software timer interrupt service routine * 3-7, 
10-4 
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Solicited interrupt 
See Device interrupt 
Spin lock ® 1-7, 3-2, 3-11 to 3-15 
See also Device lock, Fork lock, SPL, Spin lock 
index, Spin wait . 
acquisition IPL® 3-10, 3-13, A—46, C—107, 
G-17, G-19 
acquisition PC liste A~47, G—17 
address ® G—19 
dynamic ® 3-12, A—47 
multiple acquisition of ©°3—14, B—66, C-111, 
G-19 
name ® G—19 
obtaining * 3-9, B—44 to B-—45, C—107 
ownership ¢ 3-14, 16-26, A-—46, A—47, G-19 
rank® 3-12 to 3-13, 3-14, 3-15, A—46, 
G-17, G-19 
releasing ® 3-9, B—66, C-—109 
restoring *B-66, C—111 
static® 3-12, A-47 
status *G—19 
system ® 3-12, A-—47 
Spin lock data structure 
See SPL 
Spin lock index ® 3-12, 3-12 to 3-13, G-19 
Spin lock IPL vector 
See SMP$AR_IPLVEC 
Spin lock synchronization macros *® G—4, G-13 | 
See also DEVICELOCK, DEVICEUNLOCK, 
FORKLOCK, FORKUNLOCK, LOCK, and 
UNLOCK . 
Spin wait ® 3-14, A-47, C-—106, C-107, C-108 
SPL$B_IPL® 3-8, A-56, G-—17 
SPL$B_RANK ® G—17 
SPL$L_BUSY_WAITS ® G-17 
SPL$L_OWN_PC_VEC ® G-17 
SPL$O__ACQ_COUNT ® G—17 
SPL (spin lock data structure) ® A-45 to A-—47 
SPLACOERR bugcheck ® 16—25, 16-26, C-107, 
G-18 
$SPLCODDEF macro ®B-21, B-24, G-9 
SPLIPLHIGH bugcheck ® 16—25, C-107, C—108, 
G-—18 
SPLIPLLOW bugcheck ¢ 16-25, C—109, C-—110, 
C-111, C-112, G-18 
SPLRELERR bugcheck ® 16-25, 16-26, C—109, 
C-—110, G-18 
SPLRSTERR bugcheck ® 16—25, 16-26, C—111, 
C—112, G-18 
Spooled device * A-53 
SPTREO parameter ® C—16 
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SS$_ABORT ® 10-6 
SS$_ACCVIO ® C-32, C-35, C-41, C—43, C-46, 
C-—49, C-50, C-54, C-55, C-58, C-71, 
C-77, C-78 
SS$_BADPARAM ® C-32, C-—35, C—41, C—43, 
C-45, C-54, C-55, C-57, C-103 
SS$_CANCEL ® 11-6 
SS$_EXQUOTA ® C-6, C-20, C-22, G-6 
SS$_ILLIOFUNC * C-50 
SS$_INSFMAPREG ¢ C-62 
SS$_INSFMEM eC-6, C-12, C-—14, C-15, C-16, 
C-51, C-59 
SS$_INSFSPTS ® C—16, C-103 
SS$_INSFWSL ¢ C-32, C-35, C-41, C-46, C-58 
SS$_IVCHAN ® C—100 
SS$_MBFULL ® C-51, C-59 
SS$_MBTOOSML ® C-51, C-59 
SS$_NONSMPDRV ® G—4 
SS$_NOPRIV ® C-51, C-59, C-—100 
SS$_SSFAIL ® C-62, C-73, C-82, C-90 
Stack 
device driver use of © 8-1 
using for temporary storage ® 5-3 
START/CPU command ® G-21, G-—23 
Start 1/O routine ® 1-3 


See also Alternate start |/O routine 
activating ® C-28 
address ® 2—4, 6-3, A-29, D-15 
checking for zero length buffer® C—32, C-—41, 
C-54 
context® 4-12 to 4-13, 8-1 to 8-2, D-15 
entry point ®D—15 
exit method ® D—16 
for connect to interrupt facilitye 18-10, 18-15 
for MASSBUS device ® 13-12 
for MicroVAX | device driver ® 12~—26 
functions® 4-13 to 4-14 
input ® D-—15 
of CONINTERR.EXE ¢ 18-13 
reactivating® 4-15 to 4~—16 
register usage ® 8-1, D-15 
suspending ® 4-14 
synchronization requirements ® 3-6, 3-19, 
8-5, D-15, G-9to G-—11 
transferring control to®4—12 to 4-13, 8-1, 
10-3, C-38, C-68 to C-—69 
writing® 8-1 to 8-7 
Static spin lock ®3~12 
Status register 
See CSR, MBA$SL_SR 
STOP/CPU command ¢ G—22 
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STOPPED processor state ® A—15 
STOPPING processor state ® A~15 
Streamlined synchronization image ® 16-25 
loading * G—2 
Subcontroller ® A~32 
Swapping I/O function * A-39 
SWI$GL—FOFL 
replaced by CPU$Q__SWIQFL ¢ G—-15 
Symbol list 
defining®B-27 to B-28 
Synchronization image ® G—23 
full-checking ® 16-25, G-2, G-17 
streamlined *® 16-25, G—2 
uniprocessing * 16-25, G—2 
Synchronization techniques ® 1-7, 3-1 to 3-24 
See also IPL, Spin lock, Fork queue, and 
Resource wait queue 
Synchronous backplane interconnect 
See SBI 
Synchronous communications device ®¢ A-54 
SYS$ALLOC ¢ A~52, A-56 
SYS$AL__JOBCTLMB 
replaced by SYS$AR_JOBCTLMB ¢ G-7 
SYS$AL—OPRMBX 
replaced by SYS$AR_OPRMBX ¢ G-7 
SYS$AR_JOBCTLMB ¢ 9-7, G-7 
SYS$AR_OPRMBX ® 10-7, G-7 
SYSSASSIGN® 1-6, 2-3, 4-3, 18-8, A-11, 
A-55, A-56 
for template device *e D-5 
SYSSCANCEL® 1-4, 11-6, 11-7, 17-15, 
18-18, A-29, D-3 
SYS$CRMPSC® 18-5 to 18-6, 18-7 
SYS$DALLOC ® 11-7, 17-15, A-29, A-55, 
A-56, D-3 
SYS$DASSGNe 11-6, 11-7, 17-15, A-29, 
A-55, D-3 
SYS$LOADABLE_IMAGES directory *G-8 
SYS$QIO® 1-1, 2-2 to 2-4, 4-1 to 4-13, 
A-36 
device-dependent arguments of ® A-40 
for connect to interrupt facility ® 18-8, 
18-9 to 18-12 
SYS$OQIOW ¢ 2-7, A-36 
SYS$SYNCH ® 2-7 
SYSBOOT 
See Secondary bootstrap program 
System buffer 
See Buffer, Nonpaged pool 
System configuration ® 15-9 


System context ® 1-8 
System control block 
See SCB 
System Dump Analyzer (SDA) * 16—20 
current process ® G—18 
SET CPU command ® G—19 
SHOW CPU command *® G-19 
SHOW CRASH command ® G—19 
SHOW SPINLOCKS command ¢ G—19 
using to debug device driver ® 16—26 
System failure 
inducing with XDELTA ® 16-20 
System Generation Utility (SYSGEN) ¢ 
15-2 to 15-20 
AUTOCOMFIGURE command® 11-3 to 11-4, 
14-20, 15-11 to 15-20, A-2, A-33, 
A-47, B—20, D-19 
CONNECT command® 11-3 to 11-4, 14—20, 
15-2, 15-3 to 15-6, A-6, A-24, A-35, 
A-43, A-47, B-20, D-7, D-21, G—3 
/ADAPTER qualifier ® 15—5 
/ADPUNIT qualifier 15-6 
/CSR qualifier ¢ 15-5 
/CSR_OFFSET qualifier® 15-5 
/DRIVERNAME qualifier 15-6 
/MAXUNITS qualifier * 15-6 
/NOADAPTER qualifier ® 15-5 
/NUMVEC qualifiere 12-32, 12-33, 15-6, 
A-21 
/VECTOR qualifier * 15-6 
/VECTOR_OFFSET qualifier © 15-6 
device table® 15-12 to 15-13, 15-20 
LOAD command® 11-3, 15-2 to 15-3, G-3 
loading a VAXBI device driver using ® 
14-20 to 14-21 
RELOAD commande 11-4, 15-7 to 15-8, D-9 
SHOW/ADAPTER command ® 15-8 
SHOW/CONFIGURATION command ® 15-9 
SHOW/DEVICE commande 15-9 to 15-10 
System initialization ® G-22 to G-24 
System map (SYS$SYSTEM:SYS.MAP) ¢ 16-20 
System page-table entry 
allocating ® 14-15, C-103, G—7 
allocating permanent ® 6—2, A-32, A-58, B-19, 
C-77, C-78 
deallocating * C— 104 
System resource 
accessing ® B—44 to B—45 
System service dispatcher 
role in servicing I/O request ® 4—1 
System spin lock ® 3-12 
System time ® 3-7, 3-13, C-—67, G—14, G—25 
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System time (cont’d.) 
reading *B—47, G-15, G—26 


7 


Tape driver® A-53, D-12. » 
using local tape UCB extension ® A—48, 
A-60 to A-61 
Template device ® 11-11 
Template for a device driver¢5—6 to 5-15 
Template UCB e A-56, A-57 
Terminal ® A—53, A-—54 
See also Terminal controller, Terminal class 
driver, Terminal port driver, Terminal UCB 
extension 
detached ®e A-54 
1/O function for ® A-39 
redirected ® A-54 
Terminal class driver® 17—1 to 17-21 
binding to port driver® 17-8, B—7 
service routines® 17-17 to 17-21 
structure ® 17-6 
Terminal controller * A—19 
Terminal port driver® 17-1 to 17-21, B-6 
aborting output activity in® 17-15 
binding to class driver ® 17-8, B—7 
canceling !/O request in® 17—15 
control flags © A-67 
detecting an error on terminal line in® 17-21 
disconnecting a process from a terminal in® 
17-18 
forking in® 17-13, 17-18 
implementing modem functions in® 17-14 
initiate routines® 17-11 to 17-14 
managing data set state transitions in® 17-18 
obtaining characters for output in® 17-19 
passing input characters to class driver from ® 
17-19 
resuming stopped output in® 17—15 
service routines® 17-15 to 17-17 
starting output on an inactive line in® 17—14 
startup routines® 17-10 to 17-11 
stopping output in® 17-15 
structure ® 17—6 
using input flow control character in® 17-16 
Terminal UCB extension® 17-2 to 17-3, A-48, 
A-62 to A-69 
initializing ® 17-20 
remote * A—54 
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Time 
reading system ® B—47 
TIMEDWAIT macro ¢ B—64 to B-65 
See also TIMEWAIT macro 
example ¢ B—65 
Timekeeping * G—25 to G-—26 
Timeout ¢ A—56, B—72 
caused by power failure recovery procedure ® 
10-5 
detecting * A—57 
disabling® 4—14, 10-1, B-—40, C—30 
due time ® A—57 
expected ® A~56, C—102 
logging ® 10-6, 11-9 
Timeout enable bit 
See UCB$V_TIM 
Timeout handling routine ® 1-3, 3-7, 9-4, 
10-4 to 10-7, 11-8, B—72, D-4 
aborting an I/O request in® 10-6 
address ® 8-7, 10-1, D—17 
context ® 10—4, D—-17 
entry point ® D-—17 
exit method e D—18 
functions © 10—5, D—18 
input ¢D—18 
register usage ®D-17 
retrying an |/O operation in® 10-5 to 10-6 
synchronization requirements ® 3-19, D-17, 
G-13 
Timeout interval * B—72 
specifying * 10—4 
Timer 
See Software timer, Interval clock 
Timer queue * 3-13, C-29, G—14, G—25 
Timer queue element 
See TOE 
TIMER spin lock ¢3—7, 3-12, C-29, G—14, G-25 
TIMEWAIT macro * B—63 
See also TIMEDWAIT macro 
example * B—63 
TIMOUT processor state * A-15, G—21 
TIMOUT_CRASH processor state ® G—22 
TOQE$OQ_TIME ® C-29 
TQE (timer queue element) 
calling a driver from ® G-16 
expiration time * 3-7, C—29 
inserting in timer queue * C—29 
Translation buffer 
invalidating * B—38 to B-39, G—16 
TTDRIVER.EXE ¢ 17-1 
TTY$V_PC_NOTIME ® 17-14 
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TTY$V_PC_PORTFDT ¢ 17-13 

TTY$V_TP_ABORT ® 17—17 

$TTYDEFS macro e 17-2 

$TTYMACS macro® 17-11, B—6, B-7, B-67, 
B-68, B-69 

$TTYMDMDEF macro® 17-18 

$TTYMODEMDEF macro® 17-11 

$TTYUCBDEF macro ® A-48 


U 


UBA (UNIBUS adapter) ¢ 1-10 


See also UNIBUS adapter 
UBI (UNIBUS interface) © 1-11 


See also UNIBUS adapter 
UBMAPEXCED bugcheck ® C—73, C—76 
UCB$B_DEVCLASS ® 6-2, B—24, C—50 
UCB$B_DEVTYPE ® 6-2, B-24, C-50 
UCB$B_DIPL® 3-6, 6-2, 10-4, B-24 
UCB$B_ERTCNT © 10-3, C-67, C-91 
UCB$B_FIPL® A-51, B—31 
UCB$B_FLCK 3-5, 6-2, 10-1, B—-24, B-31 
initializing © G-8 
UCB$B_SLAVE ® 13-11 
UCB$B_SLAVE+1 ¢ 13-11 
UCBS$B_TP_STAT ® 17—17 
UCB$B_TT_DEPARI® 17-20 
UCB$B_TT_DETYPE ® 17—20 
UCB$B_TT_MAINT ® 17-13, 17-14 
UCB$B_TT_OUTYPE ® 17-14, 17-19, 17-20, 
17-21 
UCB$B_TT_PARITY ® 17-14, 17—20 
UCB$L_AFFINITY ®C-69 
UCB$L_CRB® 11-4, 13-12 
UCB$L_DDB ® 4-6 
UCB$L_DDT ® 17-8 
UCB$L_DEVCHAR ® 6-2, 11-9, B-24 
UCB$L_DLCK ¢ 3-20 
UCB$L_DUETIM ° 4-14, 8-7, 10-5, C—101, 
C-—102 
UCB$L_EMB ¢ 10-3, C-8 
UCB$L_FPC e 4-13, 4-14, 9-4, 10-1, 10-4 
UCB$L_FR3 °4—13, 4-14, 9-4, 10-1, 10-4 
UCB$L_FR4° 4-13, 4-14, 9-4, 10-1, 10-4 
UCB$L_IOOFL® 10-3, C-28, G-14 
UCB$L_IRP*® 4-4, 10-3, C-69 
UCB$L_LINK ¢ 11-4 
UCB$L_OPCNT ® C—5, C-24, C-91 
adjusted by IOCSREQCOM ® C-92 





UCB$L_ORB ® A-—43 
UCB$L_STS® 2-4, 8-5, 8-7 
UCB$L_SVAPTE ® 4-4, 8-2, 12-21, 13-3, 
13-13, 14-16, A—40, C-69, C-—77 
UCB$L_SVPNeB-19, C-65, C-77 
UCB$L_TT_CLASS ® 17-8, B-7 
UCB$L_TT_GETNXT ® 17-8 
UCB$L_TT_LOGUCB ® 17-20 
UCB$L_TT_OUTADRe 17-14, 17-15, 17-19, 
17-20 
UCB$SL_TT_PORT ° 17-8, B—7 
UCB$L_TT_PUTNXT ® 17-8 
UCB$L_TT_RTIMOU ¢ 17-20 
UCB$L_TT_WELINK ® 17—20 
UCB$O__DEVDEPEND ® 6-2, C—48, C-50 
UCB$V_BSY ® 2-4, 4—4, 7-5, 10-3, 11-8, 
C-28, C-66, D-4 
UCB$V_CANCEL® 10-6, 11-8, C-66, C-69, D—4 
UCB$V_DELMBX e 17-12 
UCB$V_ECC ® C-65 
UCB$V_ERLOGIP ® 10-3, 11-9, C-8, C-92 
UCB$V_INT ¢8-7, 9-3, 9-7, 10-4, 13-9, 
17-14 
UCB$V_JOB ° 9-6, 9-7, 9-8 
UCBSV_ONLINE © 9-8, 11-2, 14-11, A-35 
UCB$V_POWER® 8-5, 10-5, 11-1, 17-11 
UCBSV_TEMPLATE ® D-5 
UCB$V_TIM® 8—7, 10—1, 10-4, B—40, C-30, 
C-101 
UCB$V_TIMOUT ® 10-4, C-69, C—101 
UCB$V_VALID ¢ 9-8 
UCBSW_BCNT ¢ 8-2, 12-19, 12-21, 13-3, 
13-13, 14-16, A—40, A-58, C-62, C-64, 
C-69 
UCB$W-_BOFF 8-2, 12-19, 12-21, 12-22, 
13-3, 13-13, 14-16, A-40, A-58, C-62, 
C-64, C-69 
UCB$W_BUFQUO 
in mailbox UCB « C—59 
UCB$W_DEVBUFSIZ * 6-2, C-50 
in mailbox UCB e C-59 
UCBS$W_DEVSTS ¢ 10-3 
UCBSW_EC1 ¢C-65 
UCB$W_EC2 ¢ C-65 
UCB$W_ERRCNT ¢ 11-9, C-8 
UCB$W_QLEN ¢ C-28 
UCB$W_REFC °9-6, 9-7, 11-6, D-3 
UCB$W__TT_CURSOR ® 17—20 
UCB$W_TT_DESPEE ¢ 17-20 
UCB$W_TT_HOLD ¢ 17-20 
UCBSW_TT_OUTLEN® 17-14, 17-19, 17-20 
UCBSW_TT_PRTCTL® 17-13, 17-14 


Index 


UCBSW_TT_SPEED ® 17-14, 17-20 
UCBSW_UNIT ® 13-11 
UCB (unit control block) ® 1-5, 3-5, 4-4, A-—11, 
A-47 to A-69 
address * 8-7, 11-4 
as fork block ¢ 8—7 
as template e A—57 
cloned ¢ A-30, A-56 
creation® 11-3, 13-6, 15-4, 15-18, A-36, 
A-47 
dual path extension ®* A—48 
error log extension® 11-8, A—48, 
A-58 to A-60 
extending ® A-48 to A-49 
initializing ¢ 11-2 
local disk extension® 11-8, A—48, 
A-61 to A-62, C-9, C-65 
local tape extension® 11-8, A-—48, 
A-60 to A-61, C-9 
logical ®° A—66 
number to be created ® 6—2 
physical ® A-64 
reference count ® A—56 
remote terminal extension ® A—54 
size ® A-32, A-47 to A-49, A-51, B—20 
storing data ine 4—4, 5—1 
synchronizing access to® 2—4, 3-5, 3-15 
terminal extension® 17-2 to 17-3, A-48, 
A-62 to A-69 
$SUCBDEF macro ® A-—48 
UNIBUS 
accomplishing a DMA transfer on® 
12-15 to 12-26 
address size® 12-5 
example of driver designed for®E—1 to E-29, 
F-1 to F-25 
example of read operation® 12-12 to 12-13, 
12-14 . 
example of write operation® 12-12, 12-14 
1/O address space ® 18-1, 18-3, 18-6 
|/O space ® 12-4 
power failure * 18-6 
UNIBUS adapter® 1-11, 1-12 
error interrupt from ® 16-21, 18-6 
functions® 12-1 to 12-14 
interrupt service routine ® 12—30 
nexus value of ® 15—5 
obtaining resources of ®° 12-15 
prefetch function ® 12-12, 12—13 
registers ®° 12-15 
scatter-gather map® 12—4 to 12-7 
synchronizing access to® 12—2 
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Uniprocessing device driver 
converting to multiprocessing device driver ® 
G-8 to G-20 
incompatibility with multiprocessing device 
driver® 15-10, G-3 
Uniprocessing environment 
contrasted with multiprocessing environment ® 
3-10, G-1 
Uniprocessing synchronization image ® 16-25 
loading ®* G—2 
Unit control block 
See UCB 
Unit delivery routine * A-2 
address ®6—2, 15-18, A-33, B-20, D-19 
context ® 15-18, D-19 
entry point ® D—19 
exit method * D—20 
functions * 15~18, D—20 
input ¢D-19 
output ® 15-18 
register usage ®D-—19 
synchronization requirements ® D—19 
Unit initialization routine® 1-3, 11-1 to 11-6, 
15-4 
address ° 4-4, 6-3, 6-4, 11-1, 12-31, 
A-24, A-29, B-24, D-21 
allocating contiguous physical memory in® 
12-26 
allocating controller data channel ine 8-4, 10-2 
allocating permanent buffered data path in® 
12-18 
allocating permanent map registers in® 
12-20 to 12-21 
context® 11-1, 11-3, D-21 
entry point ®* D—21 
exit method ¢ D-21 
for connect to interrupt facility © 18-10, 
18-14 to 18-15 
for generic VAXBI device® 14-10, 14-19 
forking ine 3-21, 11-5 to 11-6 
for MASSBUS device ® 11-4, 13-11, A-24 
for MicroVAX | device * 12-26 
for terminal port driver® 17-8, 17-11 
functions ® 11-2, D—22 
input® 11-3, D-21 
of CONINTERR.EXE ® 18-14 
of terminal port driver ® B—7 
register usage ® D—2 1 
synchronization requirements ®D-—21, G—12 
UNLOCK macro ® 3-9, B-66, C-109, C-111, G-4 
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Unsolicited interrupt 
See Device interrupt 
Unsolicited interrupt service routine® 9-5, 13-14, 
A-29 
address ® 6-3, D-23 
context * D-23 
entry point ® D-23 
exit method ¢ D-23 
input *D-23 
register usage ®D-23 
synchronization requirements ® D—23 
UNSUPRTCPU bugcheck ¢ B—9 
User interface CSR space 
enabling interrupts frome 14-13 
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VAX-11/725 


See VAX-11/730 

booting with XDELTA from ® 16-4 
VAX-11/730¢8 1-12 

booting with XDELTA frome 16-4 
VAX-11/7508 1-11 

booting with XDELTA frome 16-2 
VAX-11/780¢8 1-10 

booting with XDELTA from ® 16-4 

requesting an XDELTA interrupt from® 16-8 
VAX-11/785 


See VAX-11/780 

booting with XDELTA frome 16-4 

requesting an XDELTA interrupt from ® 16-8 
VAX 6200 series® 1-12 to 1-14 

booting with XDELTA from ® 16-2 

requesting an XDELTA interrupt from ® 16-8 
VAX 82008 1-12 to 1-14 

booting with XDELTA frome 16-3, 16-8 
VAX 8250 

See VAX 8200 

booting with XDELTA from® 16-3, 16-8 
VAX 8300 

See VAX 8200 

booting with XDELTA from ® 16-3, 16-8 
VAX 8350 

See VAX 8200 

booting with XDELTA from® 16-3, 16-8 
VAX 85308 1-12 to 1-14 

booting with XDELTA frome 16-3 

requesting an XDELTA interrupt from ® 16-8 





VAX 8550 


See VAX 8530 
booting with XDELTA from ® 16-3 
requesting an XDELTA interrupt from ® 16-8 
VAX 8600 1-10 
booting with XDELTA from ® 16—4 
requesting an XDELTA interrupt from® 16-8 
VAX 8650 
See VAX 8600 
booting with XDELTA from ® 16—4 
requesting an XDELTA interrupt from ® 16—8 
VAX 8670 
See VAX 8600 
booting with XDELTA from» 16-4 
requesting an XDELTA interrupt from ® 16-8 
VAX 8700 
See VAX 8530 
booting with XDELTA from ® 16-3 
requesting an XDELTA interrupt from ¢ 16-8 
VAX 88008 1-12 to 1-14 
booting with XDELTA from® 16-3 
requesting an XDELTA interrupt from ® 16-8 
VAX 8830 
booting with XDELTA from® 16-3 
requesting an XDELTA interrupt from ® 16-8 
VAX 8840 
booting with XDELTA frome 16-3 
requesting an XDELTA interrupt from ® 16-8 
VAXBI bus ® 1-12 
address ® 14—2 to 14-5 
arbitration mode of ® 14-23 
errors ® 14—24 
1/O address space® 14-2, 14-14, 18-1 
master of ® 14-8 
memory space ® 14-2 
VAXBI node 
See also Generic VAXBI device, Node ID 
definition ® 14-1 
determining self-test status of © 14-11 
enabling BIIC options on® 14-13 
enabling error interrupts from ® 14—13 
mapping window space of® 14-14 to 14-15, 
C-—103 
setting interrupt destination of © 14—12 
setting interrupt vector for ® 14—13 
VAX MACRO instructions 
as used in device driver®5—1 to 5—4 
VCB (volume control block)® A-52, A-56 
VEC$B_DATAPATH ® 12-17, 12-18, 12-21, 
12-25 
VEC$B_NUMREG ¢ 12-20 
VEC$L_IDB ° 4-4, 13-12 
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VEC$L_INITIAL® 4—4, 15-4, D-7 
VEC$L_ISR® 4—4, D-12, G—5 
VEC$L_RTINTD ® 12-35, 12-36 
VECS$L_UNITINIT ¢4—4, 15-4, D-21 
VEC$OQ_DISPATCH ¢ A-23 
VEC$V_LWAE ® 12-14, 12-21, C-76 
VEC$V_MAPLOCK ® 12-20, C-87 
VEC$V_PATHLOCK ® 12-17, 12-18, C-84 
VECSW_MAPALT ® 12-20, 12-23 
VECSW_MAPREG ® 12-20, 12-22 
VEC$W_NUMALT ¢ 12—20 
VEC (interrupt transfer vector)® 12-30, 12-31, 
12-31 to 12-33, A-8, A-20 to A-25 
initializing * 12-32 
multiple * A—2 1 
$VECEND macro ® 17-6, B—-68 
example ® B—69 
$VECINI macro ® 17-6, B—67, B—69 
example ¢ B—-69 
$VEC macro® 17-6, B-67 
example ¢ B—-69 
VECTAB 
See Adapter dispatch table 
Vector 
fixed space ® 15-12 
floating space ® 15-12 
Vector jump table 
See Adapter dispatch table 
—VIELD macro *® A—48, B—70 to B-71 
example ® B—7 1 
$VIELD macro®B-70 to B—71 
VIRTCONS spin lock ¢ 3-13 
Virtual address 
translating to physical address ® 12-26 
Virtual address register 
See MBA$L_VAR 
Virtual 1/O function ® A-39, A—41 
translation to logical function from ¢ 2—3 
VMB 
See Primary bootstrap program 
Volume ® A—56 
Volume valid bit 
See UCB$V_VALID 


WwW 


Wait for interrupt macro 
See WFIKPCH macro, WFIRLCH macro 
WCB (window control block) ¢ 4-8, A-11, A-38 
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Index 


WFIKPCH macro ¢4—14, 8-5, 8-6, 10-7, 13-13, 
B-61, B—72 to B-73, C—101, D-17, G-11 
WFIRLCH macro® 4—14, 8-5, 8-6, 
B-72 to B-73, C-101, D-17 
Window control block 
See WCB 
Window space ® 14—5 
mapping® 14—14 to 14-15 
starting address ® 14—14 
Word count register ® 12-23 
Working set limit ® C-35, C-41 
insufficient * C—32 
Workstation device ® A-54 
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Write check 5 
enabling * A-53 

Write function 
FDT routine for® 7—8 


X 


XADRIVER.MAR®F—1 to F-25 

XDELTA 
See Delta/XDelta Utility 

XDELTA entry IPL® 3-8 

XQP (extended QIO processor)®A-11, A-52 
default © A—27 
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Please use this postage-paid form to comment on this manual. If you require a written reply to a software 
problem and are eligible to receive one under Software Performance Report (SPR) service, submit your 
comments on an SPR form. 


Thank you for your assistance. 


I rate this manual’s: Excellent Good Fair Poor 


Accuracy (software works as manual says) 
Completeness (enough information) 
Clarity (easy to understand) 

Organization (structure of subject matter) 
Figures (useful) 

Examples (useful) 

Index (ability to find topic) 

Page layout (easy to find information) 


OOOOO0O0do0o 
OOOO0O0000 
OOOO0000 
OOOO0O00do00 


I would like to see more/less 


What I like best about this manual is 


What I like least about this manual is 


I found the following errors in this manual: 
Page Description 








Additional comments or suggestions to improve this manual: 


Iam using Version of the software this manual describes. 
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